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 76 65 72 73 69 6f 6e ** Since version
0f00: 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 3.6.18, SQLite
0f10: 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 source code has
0f20: 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 been stored in t
0f30: 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 he.** <a href="h
0f40: 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c ttp://www.fossil
0f50: 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 -scm.org/">Fossi
0f60: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 l configuration
0f70: 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 management.** sy
0f80: 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 stem</a>. ^The
0f90: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
0fa0: 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 macro evaluates
0fb0: 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 to.** a string
0fc0: 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 which identifies
0fd0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 a particular ch
0fe0: 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 eck-in of SQLite
0ff0: 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 .** within its c
1000: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e onfiguration man
1010: 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 agement system.
1020: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 ^The SQLITE_SOU
1030: 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 RCE_ID.** string
1040: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 contains the da
1050: 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 te and time of t
1060: 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 he check-in (UTC
1070: 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a ) and an SHA1.**
1080: 20 68 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 hash of the ent
1090: 69 72 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e ire source tree.
10a0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
10b0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 [sqlite3_libver
10c0: 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c sion()],.** [sql
10d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f ite3_libversion_
10e0: 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 number()], [sqli
10f0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c te3_sourceid()],
1100: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 .** [sqlite_vers
1110: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ion()] and [sqli
1120: 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e te_source_id()].
1130: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
1140: 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 TE_VERSION
1150: 20 20 22 33 2e 31 34 2e 30 22 0a 23 64 65 66 69 "3.14.0".#defi
1160: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f ne SQLITE_VERSIO
1170: 4e 5f 4e 55 4d 42 45 52 20 33 30 31 34 30 30 30 N_NUMBER 3014000
1180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1190: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 SOURCE_ID "
11a0: 32 30 31 36 2d 30 37 2d 32 39 20 31 37 3a 33 36 2016-07-29 17:36
11b0: 3a 32 37 20 39 66 61 65 37 35 63 30 38 62 37 64 :27 9fae75c08b7d
11c0: 33 62 33 65 31 33 37 33 34 31 39 33 61 64 38 33 3b3e13734193ad83
11d0: 39 38 65 66 36 39 37 31 63 62 61 63 22 0a 0a 2f 98ef6971cbac"../
11e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
11f0: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 un-Time Library
1200: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a Version Numbers.
1210: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
1220: 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 ite3_version, sq
1230: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a lite3_sourceid.*
1240: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 *.** These inter
1250: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 faces provide th
1260: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 e same informati
1270: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 on as the [SQLIT
1280: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b E_VERSION],.** [
1290: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
12a0: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c UMBER], and [SQL
12b0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 ITE_SOURCE_ID] C
12c0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
12d0: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 cros.** but are
12e0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
12f0: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 the library inst
1300: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 ead of the heade
1310: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 r file. ^(Cauti
1320: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 ous.** programme
1330: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 rs might include
1340: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d assert() statem
1350: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 ents in their ap
1360: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 plication to.**
1370: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 verify that valu
1380: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 es returned by t
1390: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
13a0: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 match the macros
13b0: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 in.** the heade
13c0: 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 r, and thus ensu
13d0: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c re that the appl
13e0: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f ication is.** co
13f0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 mpiled with matc
1400: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 hing library and
1410: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a header files..*
1420: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1430: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 ><pre>.** assert
1440: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 ( sqlite3_libver
1450: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 sion_number()==S
1460: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
1470: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 MBER );.** asser
1480: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 t( strcmp(sqlite
1490: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 3_sourceid(),SQL
14a0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d ITE_SOURCE_ID)==
14b0: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 0 );.** assert(
14c0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c strcmp(sqlite3_l
14d0: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 ibversion(),SQLI
14e0: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 TE_VERSION)==0 )
14f0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
1500: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a ckquote>)^.**.**
1510: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 ^The sqlite3_ve
1520: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 rsion[] string c
1530: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 onstant contains
1540: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 the text of [SQ
1550: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a LITE_VERSION].**
1560: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 macro. ^The sq
1570: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
1580: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 () function retu
1590: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
15a0: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 the.** to the s
15b0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d qlite3_version[]
15c0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
15d0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c . The sqlite3_l
15e0: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 ibversion().** f
15f0: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 unction is provi
1600: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 ded for use in D
1610: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 LLs since DLL us
1620: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e ers usually do n
1630: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 ot have.** direc
1640: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 t access to stri
1650: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 ng constants wit
1660: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 hin the DLL. ^T
1670: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 he.** sqlite3_li
1680: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 bversion_number(
1690: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 ) function retur
16a0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 ns an integer eq
16b0: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 ual to.** [SQLIT
16c0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
16d0: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 ]. ^The sqlite3
16e0: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 _sourceid() func
16f0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a tion returns .**
1700: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
1710: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 string constant
1720: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 whose value is t
1730: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a he same as the .
1740: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 ** [SQLITE_SOURC
1750: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 E_ID] C preproce
1760: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a ssor macro..**.*
1770: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
1780: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 ite_version()] a
1790: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 nd [sqlite_sourc
17a0: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 e_id()]..*/.SQLI
17b0: 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 TE_API SQLITE_EX
17c0: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 TERN const char
17d0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b sqlite3_version[
17e0: 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f ];.SQLITE_API co
17f0: 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 nst char *SQLITE
1800: 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 _APICALL sqlite3
1810: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 _libversion(void
1820: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
1830: 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 nst char *SQLITE
1840: 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 _APICALL sqlite3
1850: 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b _sourceid(void);
1860: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
1870: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 SQLITE_APICALL s
1880: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1890: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a n_number(void);.
18a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
18b0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 Run-Time Librar
18c0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 y Compilation Op
18d0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 tions Diagnostic
18e0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
18f0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
1900: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 on_used() functi
1910: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 on returns 0 or
1920: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 1 .** indicating
1930: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 whether the spe
1940: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 cified option wa
1950: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a s defined at .**
1960: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 compile time.
1970: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 ^The SQLITE_ pre
1980: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 fix may be omitt
1990: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 ed from the .**
19a0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 option name pass
19b0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ed to sqlite3_co
19c0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
19d0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 (). .**.** ^The
19e0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
19f0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e option_get() fun
1a00: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 ction allows ite
1a10: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 rating.** over t
1a20: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f he list of optio
1a30: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 ns that were def
1a40: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 ined at compile
1a50: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 time by.** retur
1a60: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f ning the N-th co
1a70: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f mpile time optio
1a80: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e n string. ^If N
1a90: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
1aa0: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d ,.** sqlite3_com
1ab0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
1ac0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
1ad0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 pointer. ^The S
1ae0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 QLITE_ .** prefi
1af0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f x is omitted fro
1b00: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 m any strings re
1b10: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 turned by .** sq
1b20: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
1b30: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a ion_get()..**.**
1b40: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 ^Support for th
1b50: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e e diagnostic fun
1b60: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 ctions sqlite3_c
1b70: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1b80: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 d().** and sqlit
1b90: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
1ba0: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d _get() may be om
1bb0: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 itted by specify
1bc0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ing the .** [SQL
1bd0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 ITE_OMIT_COMPILE
1be0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 OPTION_DIAGS] op
1bf0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 tion at compile
1c00: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 time..**.** See
1c10: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 also: SQL functi
1c20: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 ons [sqlite_comp
1c30: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 ileoption_used()
1c40: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
1c50: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
1c60: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 et()] and the [c
1c70: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 ompile_options p
1c80: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 ragma]..*/.#ifnd
1c90: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 ef SQLITE_OMIT_C
1ca0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 OMPILEOPTION_DIA
1cb0: 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e GS.SQLITE_API in
1cc0: 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c t SQLITE_APICALL
1cd0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1ce0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 option_used(cons
1cf0: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 t char *zOptName
1d00: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
1d10: 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 nst char *SQLITE
1d20: 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 _APICALL sqlite3
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
1d40: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 et(int N);.#endi
1d50: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 f../*.** CAPI3RE
1d60: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 F: Test To See I
1d70: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 f The Library Is
1d80: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a Threadsafe.**.*
1d90: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 * ^The sqlite3_t
1da0: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 hreadsafe() func
1db0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 tion returns zer
1dc0: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 o if and only if
1dd0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 .** SQLite was c
1de0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 ompiled with mut
1df0: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 exing code omitt
1e00: 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a ed due to the.**
1e10: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
1e20: 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d AFE] compile-tim
1e30: 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 e option being s
1e40: 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 et to 0..**.** S
1e50: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d QLite can be com
1e60: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 piled with or wi
1e70: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 thout mutexes.
1e80: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c When.** the [SQL
1e90: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
1ea0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
1eb0: 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 acro is 1 or 2,
1ec0: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 mutexes.** are e
1ed0: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 nabled and SQLit
1ee0: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e e is threadsafe.
1ef0: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 When the.** [S
1f00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1f10: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a ] macro is 0, .*
1f20: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 * the mutexes ar
1f30: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 e omitted. With
1f40: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c out the mutexes,
1f50: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a it is not safe.
1f60: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 ** to use SQLite
1f70: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 concurrently fr
1f80: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 om more than one
1f90: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 thread..**.** E
1fa0: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 nabling mutexes
1fb0: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 incurs a measura
1fc0: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 ble performance
1fd0: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 penalty..** So i
1fe0: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 f speed is of ut
1ff0: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c most importance,
2000: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 it makes sense
2010: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 to disable.** th
2020: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 e mutexes. But
2030: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 for maximum safe
2040: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 ty, mutexes shou
2050: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a ld be enabled..*
2060: 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 * ^The default b
2070: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d ehavior is for m
2080: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 utexes to be ena
2090: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 bled..**.** This
20a0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
20b0: 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 e used by an app
20c0: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 lication to make
20d0: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a sure that the.*
20e0: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c * version of SQL
20f0: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c ite that it is l
2100: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 inking against w
2110: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
2120: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 .** the desired
2130: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b setting of the [
2140: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
2150: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 E] macro..**.**
2160: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f This interface o
2170: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 nly reports on t
2180: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 he compile-time
2190: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a mutex setting.**
21a0: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f of the [SQLITE_
21b0: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 THREADSAFE] flag
21c0: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 . If SQLite is
21d0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
21e0: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
21f0: 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 FE=1 or =2 then
2200: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 mutexes are enab
2210: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 led by default b
2220: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c ut.** can be ful
2230: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 ly or partially
2240: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 disabled using a
2250: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2260: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 3_config()].** w
2270: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 ith the verbs [S
2280: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
2290: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c GLETHREAD], [SQL
22a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
22b0: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b THREAD],.** or [
22c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
22d0: 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 RIALIZED]. ^(Th
22e0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
22f0: 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 f the.** sqlite3
2300: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 _threadsafe() fu
2310: 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c nction shows onl
2320: 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 y the compile-ti
2330: 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a me setting of.**
2340: 20 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 thread safety,
2350: 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 not any run-time
2360: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 changes to that
2370: 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 setting made by
2380: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 .** sqlite3_conf
2390: 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 ig(). In other w
23a0: 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e ords, the return
23b0: 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
23c0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 te3_threadsafe()
23d0: 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 .** is unchanged
23e0: 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c by calls to sql
23f0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e ite3_config().)^
2400: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b .**.** See the [
2410: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
2420: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
2430: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 r additional inf
2440: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c ormation..*/.SQL
2450: 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
2460: 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 TE_APICALL sqlit
2470: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f e3_threadsafe(vo
2480: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 id);../*.** CAPI
2490: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
24a0: 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 onnection Handle
24b0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 .** KEYWORDS: {d
24c0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
24d0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f on} {database co
24e0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a nnections}.**.**
24f0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 Each open SQLit
2500: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 e database is re
2510: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 presented by a p
2520: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
2530: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 tance of.** the
2540: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 opaque structure
2550: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 named "sqlite3"
2560: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 . It is useful
2570: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 to think of an s
2580: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 qlite3.** pointe
2590: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 r as an object.
25a0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 The [sqlite3_op
25b0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
25c0: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a open16()], and.*
25d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f * [sqlite3_open_
25e0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 v2()] interfaces
25f0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 are its constru
2600: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 ctors, and [sqli
2610: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 te3_close()].**
2620: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f and [sqlite3_clo
2630: 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 se_v2()] are its
2640: 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 destructors. T
2650: 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 here are many ot
2660: 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 her.** interface
2670: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 s (such as.** [s
2680: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2690: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 2()], [sqlite3_c
26a0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
26b0: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
26c0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
26d0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 )] to name but t
26e0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d hree) that are m
26f0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 ethods on an.**
2700: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a sqlite3 object..
2710: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
2720: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 t sqlite3 sqlite
2730: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 3;../*.** CAPI3R
2740: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 EF: 64-Bit Integ
2750: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 er Types.** KEYW
2760: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 ORDS: sqlite_int
2770: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 64 sqlite_uint64
2780: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 .**.** Because t
2790: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 here is no cross
27a0: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f -platform way to
27b0: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 specify 64-bit
27c0: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a integer types.**
27d0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 SQLite includes
27e0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 typedefs for 64
27f0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 -bit signed and
2800: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 unsigned integer
2810: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c s..**.** The sql
2820: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 ite3_int64 and s
2830: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 qlite3_uint64 ar
2840: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 e the preferred
2850: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 type definitions
2860: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f ..** The sqlite_
2870: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
2880: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 _uint64 types ar
2890: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 e supported for
28a0: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d backwards.** com
28b0: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e patibility only.
28c0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
28d0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 te3_int64 and sq
28e0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 lite_int64 types
28f0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 can store integ
2900: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 er values.** bet
2910: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 ween -9223372036
2920: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 854775808 and +9
2930: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 2233720368547758
2940: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 07 inclusive. ^
2950: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 The.** sqlite3_u
2960: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
2970: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 _uint64 types ca
2980: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 n store integer
2990: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 values .** betwe
29a0: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 en 0 and +184467
29b0: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 44073709551615 i
29c0: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 nclusive..*/.#if
29d0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 def SQLITE_INT64
29e0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 _TYPE. typedef
29f0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 SQLITE_INT64_TYP
2a00: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a E sqlite_int64;.
2a10: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
2a20: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f ed SQLITE_INT64_
2a30: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 TYPE sqlite_uint
2a40: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64;.#elif define
2a50: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 d(_MSC_VER) || d
2a60: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 efined(__BORLAND
2a70: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f C__). typedef _
2a80: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e _int64 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 5f 5f 69 6e 74 36 34 20 nsigned __int64
2ab0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
2ac0: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c else. typedef l
2ad0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c ong long int sql
2ae0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
2af0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f edef unsigned lo
2b00: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 ng long int sqli
2b10: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 te_uint64;.#endi
2b20: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 f.typedef sqlite
2b30: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 _int64 sqlite3_i
2b40: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 nt64;.typedef sq
2b50: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 lite_uint64 sqli
2b60: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a te3_uint64;../*.
2b70: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 ** If compiling
2b80: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 for a processor
2b90: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 that lacks float
2ba0: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 ing point suppor
2bb0: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 t,.** substitute
2bc0: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f integer for flo
2bd0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a ating-point..*/.
2be0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d #ifdef SQLITE_OM
2bf0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e IT_FLOATING_POIN
2c00: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c T.# define doubl
2c10: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a e sqlite3_int64.
2c20: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 #endif../*.** CA
2c30: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 PI3REF: Closing
2c40: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 A Database Conne
2c50: 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 ction.** DESTRUC
2c60: 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a TOR: sqlite3.**.
2c70: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2c80: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 close() and sqli
2c90: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 te3_close_v2() r
2ca0: 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 outines are dest
2cb0: 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 ructors.** for t
2cc0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
2cd0: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ect..** ^Calls t
2ce0: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 o sqlite3_close(
2cf0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c ) and sqlite3_cl
2d00: 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 ose_v2() return
2d10: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a [SQLITE_OK] if.*
2d20: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 * the [sqlite3]
2d30: 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 object is succes
2d40: 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 sfully destroyed
2d50: 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 and all associa
2d60: 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 ted.** resources
2d70: 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 are deallocated
2d80: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
2d90: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2da0: 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 ion is associate
2db0: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a d with unfinaliz
2dc0: 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 ed prepared.** s
2dd0: 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 tatements or unf
2de0: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f inished sqlite3_
2df0: 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 backup objects t
2e00: 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 hen sqlite3_clos
2e10: 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 e().** will leav
2e20: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
2e30: 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 onnection open a
2e40: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
2e50: 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 E_BUSY]..** ^If
2e60: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
2e70: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 () is called wit
2e80: 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 h unfinalized pr
2e90: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2ea0: 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 s.** and/or unfi
2eb0: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 nished sqlite3_b
2ec0: 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 ackups, then the
2ed0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2ee0: 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 tion becomes.**
2ef0: 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d an unusable "zom
2f00: 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 bie" which will
2f10: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 automatically be
2f20: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 deallocated whe
2f30: 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 n the.** last pr
2f40: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2f50: 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 is finalized or
2f60: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 the last sqlite
2f70: 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 3_backup is.** f
2f80: 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 inished. The sq
2f90: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
2fa0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e interface is in
2fb0: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 tended for use w
2fc0: 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 ith.** host lang
2fd0: 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 uages that are g
2fe0: 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 arbage collected
2ff0: 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 , and where the
3000: 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a order in which.*
3010: 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 * destructors ar
3020: 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 e called is arbi
3030: 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 trary..**.** App
3040: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
3050: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
3060: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 ze | finalize] a
3070: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ll [prepared sta
3080: 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 tements],.** [sq
3090: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 lite3_blob_close
30a0: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 | close] all [B
30b0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e LOB handles], an
30c0: 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 d .** [sqlite3_b
30d0: 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 ackup_finish | f
30e0: 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 inish] all [sqli
30f0: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 te3_backup] obje
3100: 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a cts associated.*
3110: 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 * with the [sqli
3120: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f te3] object prio
3130: 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 r to attempting
3140: 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a to close the obj
3150: 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c ect. ^If.** sql
3160: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 ite3_close_v2()
3170: 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b is called on a [
3180: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3190: 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 ion] that still
31a0: 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 has.** outstandi
31b0: 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ng [prepared sta
31c0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 tements], [BLOB
31d0: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 handles], and/or
31e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 .** [sqlite3_bac
31f0: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 kup] objects the
3200: 6e 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 n it returns [SQ
3210: 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 LITE_OK] and the
3220: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a deallocation.**
3230: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 of resources is
3240: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 deferred until
3250: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 all [prepared st
3260: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 atements], [BLOB
3270: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e handles],.** an
3280: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 d [sqlite3_backu
3290: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 p] objects are a
32a0: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a lso destroyed..*
32b0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c *.** ^If an [sql
32c0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 ite3] object is
32d0: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 destroyed while
32e0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
32f0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 open,.** the tr
3300: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 ansaction is aut
3310: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 omatically rolle
3320: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 d back..**.** Th
3330: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f e C parameter to
3340: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
3350: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 C)] and [sqlite3
3360: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a _close_v2(C)].**
3370: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
3380: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
3390: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 r or an [sqlite3
33a0: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 ] object pointer
33b0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
33c0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 m [sqlite3_open(
33d0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
33e0: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 n16()], or.** [s
33f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
3400: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 ], and not previ
3410: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a ously closed..**
3420: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 ^Calling sqlite
3430: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 3_close() or sql
3440: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 ite3_close_v2()
3450: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
3460: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ter.** argument
3470: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f is a harmless no
3480: 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 -op..*/.SQLITE_A
3490: 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 PI int SQLITE_AP
34a0: 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c ICALL sqlite3_cl
34b0: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 ose(sqlite3*);.S
34c0: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
34d0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c LITE_APICALL sql
34e0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 ite3_close_v2(sq
34f0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
3500: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 The type for a c
3510: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
3520: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 ..** This is leg
3530: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 acy and deprecat
3540: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 ed. It is inclu
3550: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 ded for historic
3560: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c al.** compatibil
3570: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 ity and is not d
3580: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 ocumented..*/.ty
3590: 70 65 64 65 66 20 69 6e 74 20 28 53 51 4c 49 54 pedef int (SQLIT
35a0: 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 73 71 6c 69 E_CALLBACK *sqli
35b0: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f te3_callback)(vo
35c0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 id*,int,char**,
35d0: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 char**);../*.**
35e0: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 CAPI3REF: One-St
35f0: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 ep Query Executi
3600: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 on Interface.**
3610: 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
3620: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
3630: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 3_exec() interfa
3640: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 ce is a convenie
3650: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 nce wrapper arou
3660: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 nd.** [sqlite3_p
3670: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 repare_v2()], [s
3680: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 qlite3_step()],
3690: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e and [sqlite3_fin
36a0: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 alize()],.** tha
36b0: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c t allows an appl
36c0: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d ication to run m
36d0: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e ultiple statemen
36e0: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 ts of SQL.** wit
36f0: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75 hout having to u
3700: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f se a lot of C co
3710: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de. .**.** ^The
3720: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
3730: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65 nterface runs ze
3740: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 ro or more UTF-8
3750: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d encoded,.** sem
3760: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 icolon-separate
3770: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 SQL statements p
3780: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32 assed into its 2
3790: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 nd argument,.**
37a0: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f in the context o
37b0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
37c0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 connection] pass
37d0: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74 ed in as its 1st
37e0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e .** argument. ^
37f0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
3800: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 function of the
3810: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 3rd argument to.
3820: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 ** sqlite3_exec(
3830: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 ) is not NULL, t
3840: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 hen it is invoke
3850: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c d for each resul
3860: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 t row.** coming
3870: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 out of the evalu
3880: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 ated SQL stateme
3890: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61 nts. ^The 4th a
38a0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 rgument to.** sq
38b0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
38c0: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 relayed through
38d0: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d to the 1st argum
38e0: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 ent of each.** c
38f0: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 allback invocati
3900: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c on. ^If the cal
3910: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f lback pointer to
3920: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
3930: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e ** is NULL, then
3940: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 no callback is
3950: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 ever invoked and
3960: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 result rows are
3970: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a .** ignored..**.
3980: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 ** ^If an error
3990: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 occurs while eva
39a0: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 luating the SQL
39b0: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 statements passe
39c0: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 d into.** sqlite
39d0: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 3_exec(), then e
39e0: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
39f0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e current statemen
3a00: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 t stops and.** s
3a10: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d ubsequent statem
3a20: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 ents are skipped
3a30: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 . ^If the 5th p
3a40: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
3a50: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 te3_exec().** is
3a60: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 not NULL then a
3a70: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 ny error message
3a80: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
3a90: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
3aa0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
3ab0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 3_malloc()] and
3ac0: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f passed back thro
3ad0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 ugh the 5th para
3ae0: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f meter..** To avo
3af0: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c id memory leaks,
3b00: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
3b10: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b should invoke [
3b20: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a sqlite3_free()].
3b30: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 ** on error mess
3b40: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 age strings retu
3b50: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 rned through the
3b60: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 5th parameter o
3b70: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 f.** sqlite3_exe
3b80: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72 c() after the er
3b90: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 ror message stri
3ba0: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ng is no longer
3bb0: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 needed..** ^If t
3bc0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
3bd0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 to sqlite3_exec
3be0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 () is not NULL a
3bf0: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 nd no errors.**
3c00: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 occur, then sqli
3c10: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 te3_exec() sets
3c20: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 the pointer in i
3c30: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 ts 5th parameter
3c40: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f to.** NULL befo
3c50: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a re returning..**
3c60: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 .** ^If an sqlit
3c70: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
3c80: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
3c90: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ero, the sqlite3
3ca0: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 _exec().** routi
3cb0: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 ne returns SQLIT
3cc0: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 E_ABORT without
3cd0: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c invoking the cal
3ce0: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a lback again and.
3cf0: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 ** without runni
3d00: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e ng any subsequen
3d10: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 t SQL statements
3d20: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 ..**.** ^The 2nd
3d30: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
3d40: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3d50: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
3d60: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 n is the.** numb
3d70: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
3d80: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 the result. ^T
3d90: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 he 3rd argument
3da0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 to the sqlite3_e
3db0: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 xec().** callbac
3dc0: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 k is an array of
3dd0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
3de0: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 ings obtained as
3df0: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c if from.** [sql
3e00: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
3e10: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 ()], one for eac
3e20: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 h column. ^If a
3e30: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a n element of a.*
3e40: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 * result row is
3e50: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f NULL then the co
3e60: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 rresponding stri
3e70: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 ng pointer for t
3e80: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 he.** sqlite3_ex
3e90: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 ec() callback is
3ea0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
3eb0: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d ^The 4th argum
3ec0: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 ent to the.** sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
3ee0: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 lback is an arra
3ef0: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
3f00: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 strings where e
3f10: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 ach.** entry rep
3f20: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 resents the name
3f30: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e of correspondin
3f40: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 g result column
3f50: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 as obtained.** f
3f60: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c rom [sqlite3_col
3f70: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a umn_name()]..**.
3f80: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 ** ^If the 2nd p
3f90: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
3fa0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 te3_exec() is a
3fb0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 NULL pointer, a
3fc0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e pointer.** to an
3fd0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f empty string, o
3fe0: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 r a pointer that
3ff0: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 contains only w
4000: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 hitespace and/or
4010: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 .** SQL comment
4020: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 s, then no SQL s
4030: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 tatements are ev
4040: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 aluated and the
4050: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e database.** is n
4060: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a ot changed..**.*
4070: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a * Restrictions:.
4080: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
4090: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 i> The applicati
40a0: 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 on must ensure t
40b0: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61 hat the 1st para
40c0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
40d0: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 _exec().**
40e0: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f is a valid and o
40f0: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f pen [database co
4100: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c nnection]..** <l
4110: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 i> The applicati
4120: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 on must not clos
4130: 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 e the [database
4140: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 connection] spec
4150: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 ified by.**
4160: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 the 1st paramet
4170: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
4180: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 ec() while sqlit
4190: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e e3_exec() is run
41a0: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 ning..** <li> Th
41b0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
41c0: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 st not modify th
41d0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
41e0: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f text passed into
41f0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 .** the 2nd
4200: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 parameter of sq
4210: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 lite3_exec() whi
4220: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 le sqlite3_exec(
4230: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a ) is running..**
4240: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 </ul>.*/.SQLITE
4250: 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
4260: 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f APICALL sqlite3_
4270: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a exec(. sqlite3*
4280: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
4290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
42a0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
42b0: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
42c0: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 t char *sql,
42d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
42e0: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f /* SQL to
42f0: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
4300: 0a 20 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 . int (SQLITE_C
4310: 41 4c 4c 42 41 43 4b 20 2a 63 61 6c 6c 62 61 63 ALLBACK *callbac
4320: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
4330: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a r**,char**), /*
4340: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 Callback functi
4350: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 on */. void *,
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4380: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 /* 1st argume
4390: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a nt to callback *
43a0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 /. char **errms
43b0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
43d0: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
43e0: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a ten here */.);..
43f0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
4400: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
4410: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c KEYWORDS: {resul
4420: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f t code definitio
4430: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 ns}.**.** Many S
4440: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 QLite functions
4450: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 return an intege
4460: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 r result code fr
4470: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e om the set shown
4480: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 .** here in orde
4490: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 r to indicate su
44a0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 ccess or failure
44b0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f ..**.** New erro
44c0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 r codes may be a
44d0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 dded in future v
44e0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
44f0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
4500: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 o: [extended res
4510: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 ult code definit
4520: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 ions].*/.#define
4530: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 SQLITE_OK
4540: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 0 /* Succ
4550: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f essful result */
4560: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 ./* beginning-of
4570: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a -error-codes */.
4580: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 #define SQLITE_E
4590: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 RROR 1
45a0: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 /* SQL error or
45b0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 missing database
45c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
45d0: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 TE_INTERNAL
45e0: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 2 /* Internal
45f0: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 logic error in S
4600: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 QLite */.#define
4610: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 SQLITE_PERM
4620: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 3 /* Acce
4630: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 ss permission de
4640: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nied */.#define
4650: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 SQLITE_ABORT
4660: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 4 /* Callb
4670: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 ack routine requ
4680: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a ested an abort *
4690: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
46a0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 _BUSY 5
46b0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 /* The databas
46c0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 e file is locked
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
46e0: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 TE_LOCKED
46f0: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6 /* A table i
4700: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 n the database i
4710: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 s locked */.#def
4720: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ine SQLITE_NOMEM
4730: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 7 /* A
4740: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 malloc() failed
4750: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4760: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 TE_READONLY
4770: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 8 /* Attempt t
4780: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e o write a readon
4790: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 ly database */.#
47a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
47b0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f TERRUPT 9 /
47c0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d * Operation term
47d0: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 inated by sqlite
47e0: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 3_interrupt()*/.
47f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4800: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 OERR 10
4810: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 /* Some kind of
4820: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f disk I/O error o
4830: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 ccurred */.#defi
4840: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 ne SQLITE_CORRUP
4850: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 T 11 /* Th
4860: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 e database disk
4870: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d image is malform
4880: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
4890: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 LITE_NOTFOUND
48a0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 12 /* Unknown
48b0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 opcode in sqlit
48c0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
48d0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
48e0: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 ITE_FULL
48f0: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 13 /* Insertio
4900: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 n failed because
4910: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c database is ful
4920: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
4930: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 ITE_CANTOPEN
4940: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 14 /* Unable t
4950: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 o open the datab
4960: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 ase file */.#def
4970: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f ine SQLITE_PROTO
4980: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 COL 15 /* D
4990: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f atabase lock pro
49a0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 tocol error */.#
49b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d define SQLITE_EM
49c0: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f PTY 16 /
49d0: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d * Database is em
49e0: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 pty */.#define S
49f0: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 QLITE_SCHEMA
4a00: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 17 /* The da
4a10: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 tabase schema ch
4a20: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 anged */.#define
4a30: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 SQLITE_TOOBIG
4a40: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 18 /* Stri
4a50: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 ng or BLOB excee
4a60: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f ds size limit */
4a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4a80: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 CONSTRAINT 19
4a90: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f /* Abort due to
4aa0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
4ab0: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 ation */.#define
4ac0: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 SQLITE_MISMATCH
4ad0: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 /* Data
4ae0: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a type mismatch *
4af0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4b00: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 _MISUSE 21
4b10: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 /* Library use
4b20: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f d incorrectly */
4b30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4b40: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 NOLFS 22
4b50: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 /* Uses OS feat
4b60: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 ures not support
4b70: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 ed on host */.#d
4b80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 efine SQLITE_AUT
4b90: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a H 23 /*
4ba0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 Authorization d
4bb0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 enied */.#define
4bc0: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 SQLITE_FORMAT
4bd0: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 24 /* Auxi
4be0: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 liary database f
4bf0: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 ormat error */.#
4c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 define SQLITE_RA
4c10: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f NGE 25 /
4c20: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 * 2nd parameter
4c30: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 to sqlite3_bind
4c40: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a out of range */.
4c50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
4c60: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 OTADB 26
4c70: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 /* File opened t
4c80: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 hat is not a dat
4c90: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 abase file */.#d
4ca0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
4cb0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a ICE 27 /*
4cc0: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 Notifications f
4cd0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 rom sqlite3_log(
4ce0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
4cf0: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 ITE_WARNING
4d00: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 28 /* Warnings
4d10: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f from sqlite3_lo
4d20: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 g() */.#define S
4d30: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 QLITE_ROW
4d40: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 100 /* sqlite
4d50: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 3_step() has ano
4d60: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a ther row ready *
4d70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4d80: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 _DONE 101
4d90: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 /* sqlite3_ste
4da0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 p() has finished
4db0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a executing */./*
4dc0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f end-of-error-co
4dd0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 des */../*.** CA
4de0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 PI3REF: Extended
4df0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a Result Codes.**
4e00: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 KEYWORDS: {exte
4e10: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
4e20: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a definitions}.**
4e30: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 .** In its defau
4e40: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e lt configuration
4e50: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 , SQLite API rou
4e60: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 tines return one
4e70: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a of 30 integer.*
4e80: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d * [result codes]
4e90: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 . However, expe
4ea0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e rience has shown
4eb0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a that many of.**
4ec0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f these result co
4ed0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 des are too coar
4ee0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 se-grained. The
4ef0: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 y do not provide
4f00: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f as.** much info
4f10: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 rmation about pr
4f20: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 oblems as progra
4f30: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 mmers might like
4f40: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 . In an effort
4f50: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 to.** address th
4f60: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f is, newer versio
4f70: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 ns of SQLite (ve
4f80: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 rsion 3.3.8 and
4f90: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a later) include.*
4fa0: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 * support for ad
4fb0: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 ditional result
4fc0: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 codes that provi
4fd0: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 de more detailed
4fe0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
4ff0: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 about errors. Th
5000: 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 ese [extended re
5010: 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 sult codes] are
5020: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 enabled or disab
5030: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 led.** on a per
5040: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
5050: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 ion basis using
5060: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
5070: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f extended_result_
5080: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f codes()] API. O
5090: 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 r, the extended
50a0: 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 code for.** the
50b0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f most recent erro
50c0: 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 r can be obtaine
50d0: 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 d using.** [sqli
50e0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 te3_extended_err
50f0: 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 code()]..*/.#def
5100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5110: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 _READ
5120: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5130: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
5140: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5150: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 SHORT_READ
5160: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5170: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (2<<8)).#defin
5180: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 e SQLITE_IOERR_W
5190: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 RITE
51a0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
51b0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (3<<8)).#define
51c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 SQLITE_IOERR_FS
51d0: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 YNC
51e0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
51f0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (4<<8)).#define
5200: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 SQLITE_IOERR_DIR
5210: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 _FSYNC (
5220: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5230: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 5<<8)).#define S
5240: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e QLITE_IOERR_TRUN
5250: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 CATE (S
5260: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 QLITE_IOERR | (6
5270: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5280: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 LITE_IOERR_FSTAT
5290: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
52a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c LITE_IOERR | (7<
52b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
52c0: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b ITE_IOERR_UNLOCK
52d0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
52e0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c ITE_IOERR | (8<<
52f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5300: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 TE_IOERR_RDLOCK
5310: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
5320: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 TE_IOERR | (9<<8
5330: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5340: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 E_IOERR_DELETE
5350: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5360: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 E_IOERR | (10<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 E_IOERR_BLOCKED
5390: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 E_IOERR | (11<<8
53b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
53c0: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 E_IOERR_NOMEM
53d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
53e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 E_IOERR | (12<<8
53f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5400: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 E_IOERR_ACCESS
5410: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5420: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 E_IOERR | (13<<8
5430: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5440: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 E_IOERR_CHECKRES
5450: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 ERVEDLOCK (SQLIT
5460: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 E_IOERR | (14<<8
5470: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5480: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 E_IOERR_LOCK
5490: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
54a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 E_IOERR | (15<<8
54b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
54c0: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 E_IOERR_CLOSE
54d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
54e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 E_IOERR | (16<<8
54f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5500: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 E_IOERR_DIR_CLOS
5510: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 E (SQLIT
5520: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 E_IOERR | (17<<8
5530: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5540: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 E_IOERR_SHMOPEN
5550: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5560: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 E_IOERR | (18<<8
5570: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5580: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 E_IOERR_SHMSIZE
5590: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
55a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 E_IOERR | (19<<8
55b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
55c0: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 E_IOERR_SHMLOCK
55d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
55e0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 E_IOERR | (20<<8
55f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5600: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 E_IOERR_SHMMAP
5610: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5620: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 E_IOERR | (21<<8
5630: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5640: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 E_IOERR_SEEK
5650: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5660: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 E_IOERR | (22<<8
5670: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5680: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e E_IOERR_DELETE_N
5690: 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 OENT (SQLIT
56a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 E_IOERR | (23<<8
56b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
56c0: 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 E_IOERR_MMAP
56d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
56e0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 E_IOERR | (24<<8
56f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5700: 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 E_IOERR_GETTEMPP
5710: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 ATH (SQLIT
5720: 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 E_IOERR | (25<<8
5730: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5740: 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 E_IOERR_CONVPATH
5750: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5760: 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 E_IOERR | (26<<8
5770: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5780: 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 E_IOERR_VNODE
5790: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
57a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 E_IOERR | (27<<8
57b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
57c0: 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 E_IOERR_AUTH
57d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
57e0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 E_IOERR | (28<<8
57f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5800: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 E_LOCKED_SHAREDC
5810: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 ACHE (SQLIT
5820: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c E_LOCKED | (1<<
5830: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5840: 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 TE_BUSY_RECOVERY
5850: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
5860: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c TE_BUSY | (1<
5870: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5880: 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f ITE_BUSY_SNAPSHO
5890: 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c T (SQL
58a0: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 ITE_BUSY | (2
58b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
58c0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f LITE_CANTOPEN_NO
58d0: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 TEMPDIR (SQ
58e0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 LITE_CANTOPEN |
58f0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
5900: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f SQLITE_CANTOPEN_
5910: 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 ISDIR (
5920: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 SQLITE_CANTOPEN
5930: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (2<<8)).#defin
5940: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 e SQLITE_CANTOPE
5950: 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 N_FULLPATH
5960: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 (SQLITE_CANTOPE
5970: 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 N | (3<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
5990: 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 PEN_CONVPATH
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f (SQLITE_CANTO
59b0: 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 PEN | (4<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 efine SQLITE_COR
59d0: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 RUPT_VTAB
59e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 (SQLITE_COR
59f0: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 RUPT | (1<<8)).#
5a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
5a10: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 ADONLY_RECOVERY
5a20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 (SQLITE_RE
5a30: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 ADONLY | (1<<8))
5a40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5a50: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 READONLY_CANTLOC
5a60: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f K (SQLITE_
5a70: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 READONLY | (2<<8
5a80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5a90: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 E_READONLY_ROLLB
5aa0: 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 ACK (SQLIT
5ab0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c E_READONLY | (3<
5ac0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5ad0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d ITE_READONLY_DBM
5ae0: 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c OVED (SQL
5af0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 ITE_READONLY | (
5b00: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 4<<8)).#define S
5b10: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c QLITE_ABORT_ROLL
5b20: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 BACK (S
5b30: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 QLITE_ABORT | (2
5b40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5b50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
5b60: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 CHECK (SQ
5b70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
5b80: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
5b90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
5ba0: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 INT_COMMITHOOK
5bb0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
5bc0: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 INT | (2<<8)).#d
5bd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
5be0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b STRAINT_FOREIGNK
5bf0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e EY (SQLITE_CON
5c00: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 STRAINT | (3<<8)
5c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5c20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 _CONSTRAINT_FUNC
5c30: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 TION (SQLITE
5c40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 _CONSTRAINT | (4
5c50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5c60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
5c70: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 NOTNULL (SQ
5c80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
5c90: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (5<<8)).#defin
5ca0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
5cb0: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 INT_PRIMARYKEY
5cc0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
5cd0: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 INT | (6<<8)).#d
5ce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
5cf0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 STRAINT_TRIGGER
5d00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e (SQLITE_CON
5d10: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 STRAINT | (7<<8)
5d20: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5d30: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 _CONSTRAINT_UNIQ
5d40: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 UE (SQLITE
5d50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 _CONSTRAINT | (8
5d60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5d70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
5d80: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 VTAB (SQ
5d90: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
5da0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (9<<8)).#defin
5db0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
5dc0: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 INT_ROWID
5dd0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
5de0: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 INT |(10<<8)).#d
5df0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
5e00: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 ICE_RECOVER_WAL
5e10: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 (SQLITE_NOT
5e20: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 ICE | (1<<8)).#d
5e30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
5e40: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c ICE_RECOVER_ROLL
5e50: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 BACK (SQLITE_NOT
5e60: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 ICE | (2<<8)).#d
5e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 efine SQLITE_WAR
5e80: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 NING_AUTOINDEX
5e90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 (SQLITE_WAR
5ea0: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 NING | (1<<8)).#
5eb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 define SQLITE_AU
5ec0: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 TH_USER
5ed0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 (SQLITE_AU
5ee0: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 TH | (1<<8)).#de
5ef0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c fine SQLITE_OK_L
5f00: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 OAD_PERMANENTLY
5f10: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c (SQLITE_OK |
5f20: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 (1<<8))../*.**
5f30: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
5f40: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 For File Open Op
5f50: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 erations.**.** T
5f60: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 hese bit values
5f70: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 are intended for
5f80: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 use in the.** 3
5f90: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
5fa0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 the [sqlite3_ope
5fb0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 n_v2()] interfac
5fc0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 e and.** in the
5fd0: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
5fe0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
5ff0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e s.xOpen] method.
6000: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
6010: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
6020: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6030: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 001 /* Ok for s
6040: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
6050: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6060: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
6070: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 E 0x00000
6080: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 002 /* Ok for s
6090: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
60a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
60b0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 TE_OPEN_CREATE
60c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
60d0: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 004 /* Ok for s
60e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
60f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6100: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
6110: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 CLOSE 0x00000
6120: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 008 /* VFS only
6130: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6140: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
6150: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 E 0x00000
6160: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 010 /* VFS only
6170: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6180: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 TE_OPEN_AUTOPROX
6190: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 Y 0x00000
61a0: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 020 /* VFS only
61b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
61c0: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 TE_OPEN_URI
61d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
61e0: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 040 /* Ok for s
61f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
6200: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6210: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 TE_OPEN_MEMORY
6220: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6230: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 080 /* Ok for s
6240: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
6250: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6260: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 TE_OPEN_MAIN_DB
6270: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6280: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 100 /* VFS only
6290: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
62a0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 TE_OPEN_TEMP_DB
62b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
62c0: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 200 /* VFS only
62d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
62e0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e TE_OPEN_TRANSIEN
62f0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 T_DB 0x00000
6300: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 400 /* VFS only
6310: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6320: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 TE_OPEN_MAIN_JOU
6330: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 RNAL 0x00000
6340: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 800 /* VFS only
6350: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6360: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 TE_OPEN_TEMP_JOU
6370: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 RNAL 0x00001
6380: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
6390: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
63a0: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e TE_OPEN_SUBJOURN
63b0: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 AL 0x00002
63c0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
63d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
63e0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a TE_OPEN_MASTER_J
63f0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 OURNAL 0x00004
6400: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
6410: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6420: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 TE_OPEN_NOMUTEX
6430: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 0x00008
6440: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
6450: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
6460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6470: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
6480: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 X 0x00010
6490: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
64a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
64b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
64c0: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
64d0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 CHE 0x00020
64e0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
64f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
6500: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6510: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
6520: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 ACHE 0x00040
6530: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 000 /* Ok for s
6540: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
6550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6560: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 TE_OPEN_WAL
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 0x00080
6580: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 000 /* VFS only
6590: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 */../* Reserved
65a0: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 :
65b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 0x00F0
65c0: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 0000 */../*.** C
65d0: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 API3REF: Device
65e0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a Characteristics.
65f0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 **.** The xDevic
6600: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 eCharacteristics
6610: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b method of the [
6620: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
6630: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 ds].** object re
6640: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 turns an integer
6650: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 which is a vect
6660: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 or of these.** b
6670: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 it values expres
6680: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 sing I/O charact
6690: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 eristics of the
66a0: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 mass storage.**
66b0: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 device that hold
66c0: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 s the file that
66d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
66e0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 methods].** refe
66f0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rs to..**.** The
6700: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6710: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 OMIC property me
6720: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 ans that all wri
6730: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 tes of.** any si
6740: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 ze are atomic.
6750: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
6760: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 _ATOMICnnn value
6770: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 s.** mean that w
6780: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 rites of blocks
6790: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 that are nnn byt
67a0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a es in size and.*
67b0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f * are aligned to
67c0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 an address whic
67d0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 h is an integer
67e0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e multiple of.** n
67f0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 nn are atomic.
6800: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
6810: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c _SAFE_APPEND val
6820: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 ue means.** that
6830: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 when data is ap
6840: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 pended to a file
6850: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 , the data is ap
6860: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 pended.** first
6870: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 then the size of
6880: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 the file is ext
6890: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 ended, never the
68a0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 other.** way ar
68b0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 ound. The SQLIT
68c0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
68d0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e AL property mean
68e0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d s that.** inform
68f0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e ation is written
6900: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 to disk in the
6910: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 same order as ca
6920: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 lls.** to xWrite
6930: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f (). The SQLITE_
6940: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f IOCAP_POWERSAFE_
6950: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 OVERWRITE proper
6960: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a ty means that.**
6970: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f after reboot fo
6980: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 llowing a crash
6990: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 or power loss, t
69a0: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e he only bytes in
69b0: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 a.** file that
69c0: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 were written at
69d0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
69e0: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 level might have
69f0: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 changed.** and
6a00: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 that adjacent by
6a10: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 tes, even bytes
6a20: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 within the same
6a30: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 sector are.** gu
6a40: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 aranteed to be u
6a50: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 nchanged. The S
6a60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 QLITE_IOCAP_UNDE
6a70: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 LETABLE_WHEN_OPE
6a80: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 N.** flag indica
6a90: 74 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 te that a file c
6aa0: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 annot be deleted
6ab0: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 when open. The
6ac0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 .** SQLITE_IOCAP
6ad0: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 _IMMUTABLE flag
6ae0: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 indicates that t
6af0: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a he file is on.**
6b00: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 read-only media
6b10: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 and cannot be c
6b20: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 hanged even by p
6b30: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a rocesses with.**
6b40: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c elevated privil
6b50: 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 eges..*/.#define
6b60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6b70: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 OMIC
6b80: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 0x00000001.
6b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6ba0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 OCAP_ATOMIC512
6bb0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6bc0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 000002.#define S
6bd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6be0: 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 IC1K
6bf0: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 0x00000004.#d
6c00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
6c10: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 AP_ATOMIC2K
6c20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
6c30: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 0008.#define SQL
6c40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
6c50: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 4K
6c60: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 0x00000010.#def
6c70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6c80: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 _ATOMIC8K
6c90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6ca0: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 20.#define SQLIT
6cb0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 E_IOCAP_ATOMIC16
6cc0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 K 0
6cd0: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e x00000040.#defin
6ce0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6cf0: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 TOMIC32K
6d00: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0x00000080
6d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6d20: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 IOCAP_ATOMIC64K
6d30: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6d40: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 0000100.#define
6d50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 SQLITE_IOCAP_SAF
6d60: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 E_APPEND
6d70: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 0x00000200.#
6d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6d90: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 CAP_SEQUENTIAL
6da0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6db0: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00400.#define SQ
6dc0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c LITE_IOCAP_UNDEL
6dd0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e ETABLE_WHEN_OPEN
6de0: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 0x00000800.#de
6df0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6e00: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 P_POWERSAFE_OVER
6e10: 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 WRITE 0x00001
6e20: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 000.#define SQLI
6e30: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 TE_IOCAP_IMMUTAB
6e40: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 LE
6e50: 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 0x00002000../*.*
6e60: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 * CAPI3REF: File
6e70: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a Locking Levels.
6e80: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 **.** SQLite use
6e90: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 s one of these i
6ea0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 nteger values as
6eb0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 the second.** a
6ec0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 rgument to calls
6ed0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 it makes to the
6ee0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
6ef0: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a lock() methods.*
6f00: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 * of an [sqlite3
6f10: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
6f20: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ect..*/.#define
6f30: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
6f40: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 0.#def
6f50: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
6f60: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a SHARED 1.
6f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
6f80: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 OCK_RESERVED
6f90: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
6fa0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 TE_LOCK_PENDING
6fb0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
6fc0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c SQLITE_LOCK_EXCL
6fd0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a USIVE 4../*.
6fe0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e ** CAPI3REF: Syn
6ff0: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 chronization Typ
7000: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 e Flags.**.** Wh
7010: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 en SQLite invoke
7020: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 s the xSync() me
7030: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 thod of an.** [s
7040: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
7050: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 s] object it use
7060: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 s a combination
7070: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 of.** these inte
7080: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 ger values as th
7090: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
70a0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 t..**.** When th
70b0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
70c0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 TAONLY flag is u
70d0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 sed, it means th
70e0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f at the.** sync o
70f0: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 peration only ne
7100: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 eds to flush dat
7110: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 a to mass storag
7120: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 e. Inode.** inf
7130: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f ormation need no
7140: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 t be flushed. If
7150: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 the lower four
7160: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 bits of the flag
7170: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 .** equal SQLITE
7180: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 _SYNC_NORMAL, th
7190: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 at means to use
71a0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 normal fsync() s
71b0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 emantics..** If
71c0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 the lower four b
71d0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 its equal SQLITE
71e0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 _SYNC_FULL, that
71f0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 means.** to use
7200: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 Mac OS X style
7210: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 fullsync instead
7220: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a of fsync()..**.
7230: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 ** Do not confus
7240: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e e the SQLITE_SYN
7250: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c C_NORMAL and SQL
7260: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c ITE_SYNC_FULL fl
7270: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ags.** with the
7280: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e [PRAGMA synchron
7290: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 ous]=NORMAL and
72a0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e [PRAGMA synchron
72b0: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 ous]=FULL.** set
72c0: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e tings. The [syn
72d0: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d chronous pragma]
72e0: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e determines when
72f0: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a calls to the.**
7300: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f xSync VFS metho
7310: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c d occur and appl
7320: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 ies uniformly ac
7330: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 ross all platfor
7340: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 ms..** The SQLIT
7350: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e E_SYNC_NORMAL an
7360: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 d SQLITE_SYNC_FU
7370: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 LL flags determi
7380: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 ne how.** energe
7390: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 tic or rigorous
73a0: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 or forceful the
73b0: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 sync operations
73c0: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 are and.** only
73d0: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 make a differenc
73e0: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 e on Mac OSX for
73f0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c the default SQL
7400: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 ite code..** (Th
7410: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d ird-party VFS im
7420: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 plementations mi
7430: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 ght also make th
7440: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a e distinction.**
7450: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f between SQLITE_
7460: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
7470: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
7480: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a , but among the.
7490: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ** operating sys
74a0: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 tems natively su
74b0: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 pported by SQLit
74c0: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a e, only Mac OSX.
74d0: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 ** cares about t
74e0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a he difference.).
74f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
7500: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 E_SYNC_NORMAL
7510: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 0x00002.#de
7520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 fine SQLITE_SYNC
7530: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 _FULL 0
7540: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 x00003.#define S
7550: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
7560: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 NLY 0x00010
7570: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
7580: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f : OS Interface O
7590: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a pen File Handle.
75a0: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 **.** An [sqlite
75b0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 3_file] object r
75c0: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 epresents an ope
75d0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a n file in the .*
75e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c * [sqlite3_vfs |
75f0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 OS interface la
7600: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 yer]. Individua
7610: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a l OS interface.*
7620: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
7630: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 s will.** want t
7640: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 o subclass this
7650: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 object by append
7660: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 ing additional f
7670: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 ields.** for the
7680: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 ir own use. The
7690: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 pMethods entry
76a0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
76b0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 an.** [sqlite3_i
76c0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
76d0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d t that defines m
76e0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f ethods for perfo
76f0: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 rming.** I/O ope
7700: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f rations on the o
7710: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 pen file..*/.typ
7720: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
7730: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 te3_file sqlite3
7740: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 _file;.struct sq
7750: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 lite3_file {. c
7760: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 onst struct sqli
7770: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a te3_io_methods *
7780: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 pMethods; /* Me
7790: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 thods for an ope
77a0: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a n file */.};../*
77b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
77c0: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 Interface File
77d0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 Virtual Methods
77e0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 Object.**.** Eve
77f0: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 ry file opened b
7800: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 y the [sqlite3_v
7810: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 fs.xOpen] method
7820: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a populates an.**
7830: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
7840: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 object (or, more
7850: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 commonly, a sub
7860: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 class of the.**
7870: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
7880: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f bject) with a po
7890: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
78a0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
78b0: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a ect..** This obj
78c0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
78d0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 methods used to
78e0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 perform various
78f0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 operations.** ag
7900: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 ainst the open f
7910: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 ile represented
7920: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
7930: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a file] object..**
7940: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 .** If the [sqli
7950: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d te3_vfs.xOpen] m
7960: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 ethod sets the s
7970: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 qlite3_file.pMet
7980: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a hods element .**
7990: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 to a non-NULL p
79a0: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 ointer, then the
79b0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
79c0: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f ods.xClose metho
79d0: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f d.** may be invo
79e0: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 ked even if the
79f0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
7a00: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 en] reported tha
7a10: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 t it failed. Th
7a20: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f e.** only way to
7a30: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 prevent a call
7a40: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 to xClose follow
7a50: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 ing a failed [sq
7a60: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
7a70: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b .** is for the [
7a80: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 sqlite3_vfs.xOpe
7a90: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 n] to set the sq
7aa0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
7ab0: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 ods element.** t
7ac0: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 o NULL..**.** Th
7ad0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
7ae0: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 to xSync may be
7af0: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
7b00: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a SYNC_NORMAL] or.
7b10: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f ** [SQLITE_SYNC_
7b20: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 FULL]. The firs
7b30: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 t choice is the
7b40: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a normal fsync()..
7b50: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 ** The second ch
7b60: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 oice is a Mac OS
7b70: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e X style fullsyn
7b80: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f c. The [SQLITE_
7b90: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a SYNC_DATAONLY].*
7ba0: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 * flag may be OR
7bb0: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 ed in to indicat
7bc0: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 e that only the
7bd0: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 data of the file
7be0: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 .** and not its
7bf0: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 inode needs to b
7c00: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 e synced..**.**
7c10: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 The integer valu
7c20: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e es to xLock() an
7c30: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 d xUnlock() are
7c40: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a one of.** <ul>.*
7c50: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c * <li> [SQLITE_L
7c60: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c OCK_NONE],.** <l
7c70: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f i> [SQLITE_LOCK_
7c80: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e SHARED],.** <li>
7c90: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 [SQLITE_LOCK_RE
7ca0: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e SERVED],.** <li>
7cb0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 [SQLITE_LOCK_PE
7cc0: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c NDING], or.** <l
7cd0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f i> [SQLITE_LOCK_
7ce0: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c EXCLUSIVE]..** <
7cf0: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 /ul>.** xLock()
7d00: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f increases the lo
7d10: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 ck. xUnlock() de
7d20: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b creases the lock
7d30: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 ..** The xCheckR
7d40: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 eservedLock() me
7d50: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 thod checks whet
7d60: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 her any database
7d70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 connection,.**
7d80: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 either in this p
7d90: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d rocess or in som
7da0: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c e other process,
7db0: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 is holding a RE
7dc0: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 SERVED,.** PENDI
7dd0: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 NG, or EXCLUSIVE
7de0: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c lock on the fil
7df0: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 e. It returns t
7e00: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 rue.** if such a
7e10: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 lock exists and
7e20: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 false otherwise
7e30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c ..**.** The xFil
7e40: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f eControl() metho
7e50: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 d is a generic i
7e60: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c nterface that al
7e70: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 lows custom.** V
7e80: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
7e90: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 ns to directly c
7ea0: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 ontrol an open f
7eb0: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a ile using the.**
7ec0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
7ed0: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 ontrol()] interf
7ee0: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 ace. The second
7ef0: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 "op" argument i
7f00: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 s an.** integer
7f10: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 opcode. The thi
7f20: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 rd argument is a
7f30: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 generic pointer
7f40: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 intended to.**
7f50: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 point to a struc
7f60: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f ture that may co
7f70: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 ntain arguments
7f80: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 or space in whic
7f90: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 h to.** write re
7fa0: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f turn values. Po
7fb0: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 tential uses for
7fc0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 xFileControl()
7fd0: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 might be.** func
7fe0: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 tions to enable
7ff0: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 blocking locks w
8000: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f ith timeouts, to
8010: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c change the.** l
8020: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 ocking strategy
8030: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 (for example to
8040: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 use dot-file loc
8050: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a ks), to inquire.
8060: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 ** about the sta
8070: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f tus of a lock, o
8080: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 r to break stale
8090: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c locks. The SQL
80a0: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 ite.** core rese
80b0: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 rves all opcodes
80c0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 less than 100 f
80d0: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a or its own use..
80e0: 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 ** A [file contr
80f0: 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 ol opcodes | lis
8100: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 t of opcodes] le
8110: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 ss than 100 is a
8120: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 vailable..** App
8130: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 lications that d
8140: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 efine a custom x
8150: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
8160: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 od should use op
8170: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 codes.** greater
8180: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f than 100 to avo
8190: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 id conflicts. V
81a0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
81b0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ns should.** ret
81c0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 urn [SQLITE_NOTF
81d0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 OUND] for file c
81e0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 ontrol opcodes t
81f0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
8200: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a ** recognize..**
8210: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 .** The xSectorS
8220: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 ize() method ret
8230: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 urns the sector
8240: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 size of the.** d
8250: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 evice that under
8260: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 lies the file.
8270: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 The sector size
8280: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 is the.** minimu
8290: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e m write that can
82a0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 be performed wi
82b0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 thout disturbing
82c0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 .** other bytes
82d0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 in the file. Th
82e0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 e xDeviceCharact
82f0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 eristics().** me
8300: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 thod returns a b
8310: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 it vector descri
8320: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f bing behaviors o
8330: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 f the.** underly
8340: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a ing device:.**.*
8350: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
8360: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
8370: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 MIC].** <li> [SQ
8380: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8390: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C512].** <li> [S
83a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
83b0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC1K].** <li> [S
83c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
83d0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC2K].** <li> [S
83e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
83f0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC4K].** <li> [S
8400: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
8410: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC8K].** <li> [S
8420: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
8430: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC16K].** <li> [
8440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
8450: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC32K].** <li>
8460: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
8470: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC64K].** <li>
8480: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
8490: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c AFE_APPEND].** <
84a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
84b0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a P_SEQUENTIAL].**
84c0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ul>.**.** The
84d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
84e0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 OMIC property me
84f0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 ans that all wri
8500: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 tes of.** any si
8510: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 ze are atomic.
8520: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
8530: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 _ATOMICnnn value
8540: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 s.** mean that w
8550: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 rites of blocks
8560: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 that are nnn byt
8570: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a es in size and.*
8580: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f * are aligned to
8590: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 an address whic
85a0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 h is an integer
85b0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e multiple of.** n
85c0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 nn are atomic.
85d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
85e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c _SAFE_APPEND val
85f0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 ue means.** that
8600: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 when data is ap
8610: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 pended to a file
8620: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 , the data is ap
8630: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 pended.** first
8640: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 then the size of
8650: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 the file is ext
8660: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 ended, never the
8670: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 other.** way ar
8680: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 ound. The SQLIT
8690: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
86a0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e AL property mean
86b0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d s that.** inform
86c0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e ation is written
86d0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 to disk in the
86e0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 same order as ca
86f0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 lls.** to xWrite
8700: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 ()..**.** If xRe
8710: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c ad() returns SQL
8720: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f ITE_IOERR_SHORT_
8730: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 READ it must als
8740: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 o fill.** in the
8750: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 unread portions
8760: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 of the buffer w
8770: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 ith zeros. A VF
8780: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 S that.** fails
8790: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f to zero-fill sho
87a0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 rt reads might s
87b0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f eem to work. Ho
87c0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 wever,.** failur
87d0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 e to zero-fill s
87e0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 hort reads will
87f0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 eventually lead
8800: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 to.** database c
8810: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 orruption..*/.ty
8820: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
8830: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 ite3_io_methods
8840: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
8850: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 ds;.struct sqlit
8860: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a e3_io_methods {.
8870: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a int iVersion;.
8880: 20 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 41 int (SQLITE_CA
8890: 4c 4c 42 41 43 4b 20 2a 78 43 6c 6f 73 65 29 28 LLBACK *xClose)(
88a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a sqlite3_file*);.
88b0: 20 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 41 int (SQLITE_CA
88c0: 4c 4c 42 41 43 4b 20 2a 78 52 65 61 64 29 28 73 LLBACK *xRead)(s
88d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f qlite3_file*, vo
88e0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 id*, int iAmt, s
88f0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
8900: 73 74 29 3b 0a 20 20 69 6e 74 20 28 53 51 4c 49 st);. int (SQLI
8910: 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 57 72 TE_CALLBACK *xWr
8920: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ite)(sqlite3_fil
8930: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c e*, const void*,
8940: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 int iAmt, sqlit
8950: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b e3_int64 iOfst);
8960: 0a 20 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 . int (SQLITE_C
8970: 41 4c 4c 42 41 43 4b 20 2a 78 54 72 75 6e 63 61 ALLBACK *xTrunca
8980: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 te)(sqlite3_file
8990: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
89a0: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 53 size);. int (S
89b0: 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a QLITE_CALLBACK *
89c0: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 xSync)(sqlite3_f
89d0: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 ile*, int flags)
89e0: 3b 0a 20 20 69 6e 74 20 28 53 51 4c 49 54 45 5f ;. int (SQLITE_
89f0: 43 41 4c 4c 42 41 43 4b 20 2a 78 46 69 6c 65 53 CALLBACK *xFileS
8a00: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ize)(sqlite3_fil
8a10: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
8a20: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 4 *pSize);. int
8a30: 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 (SQLITE_CALLBAC
8a40: 4b 20 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 K *xLock)(sqlite
8a50: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
8a60: 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 41 4c int (SQLITE_CAL
8a70: 4c 42 41 43 4b 20 2a 78 55 6e 6c 6f 63 6b 29 28 LBACK *xUnlock)(
8a80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
8a90: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 53 51 4c 49 nt);. int (SQLI
8aa0: 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 43 68 TE_CALLBACK *xCh
8ab0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 eckReservedLock)
8ac0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8ad0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
8ae0: 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 41 4c int (SQLITE_CAL
8af0: 4c 42 41 43 4b 20 2a 78 46 69 6c 65 43 6f 6e 74 LBACK *xFileCont
8b00: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c rol)(sqlite3_fil
8b10: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 e*, int op, void
8b20: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 *pArg);. int (
8b30: 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 SQLITE_CALLBACK
8b40: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 *xSectorSize)(sq
8b50: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
8b60: 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c int (SQLITE_CALL
8b70: 42 41 43 4b 20 2a 78 44 65 76 69 63 65 43 68 61 BACK *xDeviceCha
8b80: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 racteristics)(sq
8b90: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
8ba0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 /* Methods above
8bb0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 are valid for v
8bc0: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e ersion 1 */. in
8bd0: 74 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 t (SQLITE_CALLBA
8be0: 43 4b 20 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c CK *xShmMap)(sql
8bf0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
8c00: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 iPg, int pgsz, i
8c10: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c nt, void volatil
8c20: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 53 51 4c e**);. int (SQL
8c30: 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 53 ITE_CALLBACK *xS
8c40: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f hmLock)(sqlite3_
8c50: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 file*, int offse
8c60: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c t, int n, int fl
8c70: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 53 51 ags);. void (SQ
8c80: 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 LITE_CALLBACK *x
8c90: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 ShmBarrier)(sqli
8ca0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e te3_file*);. in
8cb0: 74 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 t (SQLITE_CALLBA
8cc0: 43 4b 20 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 CK *xShmUnmap)(s
8cd0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
8ce0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 t deleteFlag);.
8cf0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 /* Methods abov
8d00: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 e are valid for
8d10: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 version 2 */. i
8d20: 6e 74 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 nt (SQLITE_CALLB
8d30: 41 43 4b 20 2a 78 46 65 74 63 68 29 28 73 71 6c ACK *xFetch)(sql
8d40: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 ite3_file*, sqli
8d50: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c te3_int64 iOfst,
8d60: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 int iAmt, void
8d70: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 53 51 **pp);. int (SQ
8d80: 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 LITE_CALLBACK *x
8d90: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 Unfetch)(sqlite3
8da0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f _file*, sqlite3_
8db0: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 int64 iOfst, voi
8dc0: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 d *p);. /* Meth
8dd0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 ods above are va
8de0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 lid for version
8df0: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 3 */. /* Additi
8e00: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 onal methods may
8e10: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
8e20: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a ure releases */.
8e30: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
8e40: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c EF: Standard Fil
8e50: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 e Control Opcode
8e60: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
8e70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 file control opc
8e80: 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 odes} {file cont
8e90: 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a rol opcode}.**.*
8ea0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
8eb0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 constants are op
8ec0: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 codes for the xF
8ed0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
8ee0: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c d.** of the [sql
8ef0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
8f00: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 object and for
8f10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
8f20: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 e_control()].**
8f30: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
8f40: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 <ul>.** <li>[[S
8f50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b QLITE_FCNTL_LOCK
8f60: 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b STATE]].** The [
8f70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 SQLITE_FCNTL_LOC
8f80: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 KSTATE] opcode i
8f90: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 s used for debug
8fa0: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f ging. This.** o
8fb0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 pcode causes the
8fc0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
8fd0: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 thod to write th
8fe0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 e current state
8ff0: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 of.** the lock (
9000: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c one of [SQLITE_L
9010: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 OCK_NONE], [SQLI
9020: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c TE_LOCK_SHARED],
9030: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b .** [SQLITE_LOCK
9040: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c _RESERVED], [SQL
9050: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
9060: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f ], or [SQLITE_LO
9070: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a CK_EXCLUSIVE]).*
9080: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 * into an intege
9090: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 r that the pArg
90a0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 argument points
90b0: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c to. This capabil
90c0: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 ity.** is used d
90d0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e uring testing an
90e0: 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 d is only availa
90f0: 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53 51 4c ble when the SQL
9100: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 ITE_TEST.** comp
9110: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
9120: 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c is used..**.** <
9130: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
9140: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a L_SIZE_HINT]].**
9150: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
9160: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 TL_SIZE_HINT] op
9170: 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20 code is used by
9180: 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 SQLite to give t
9190: 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 he VFS.** layer
91a0: 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 a hint of how la
91b0: 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 rge the database
91c0: 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 file will grow
91d0: 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 to be during the
91e0: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e .** current tran
91f0: 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 saction. This h
9200: 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 int is not guara
9210: 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 nteed to be accu
9220: 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 rate but it.** i
9230: 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 s often close.
9240: 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 The underlying V
9250: 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 FS might choose
9260: 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 to preallocate d
9270: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 atabase.** file
9280: 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 space based on t
9290: 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 his hint in orde
92a0: 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 r to help writes
92b0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 to the database
92c0: 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 .** file run fas
92d0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ter..**.** <li>[
92e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 [SQLITE_FCNTL_CH
92f0: 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 UNK_SIZE]].** Th
9300: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
9310: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f CHUNK_SIZE] opco
9320: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 de is used to re
9330: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 quest that the V
9340: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e FS.** extends an
9350: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 d truncates the
9360: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e database file in
9370: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a chunks of a siz
9380: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 e specified.** b
9390: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 y the user. The
93a0: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 fourth argument
93b0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 to [sqlite3_file
93c0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 _control()] shou
93d0: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 ld .** point to
93e0: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 an integer (type
93f0: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 int) containing
9400: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 the new chunk-s
9410: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f ize to use.** fo
9420: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 r the nominated
9430: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 database. Alloca
9440: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 ting database fi
9450: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 le space in larg
9460: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 e.** chunks (say
9470: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 1MB at a time),
9480: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 may reduce file
9490: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 -system fragment
94a0: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 ation and.** imp
94b0: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 rove performance
94c0: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 on some systems
94d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
94e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f LITE_FCNTL_FILE_
94f0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 POINTER]].** The
9500: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 [SQLITE_FCNTL_F
9510: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 ILE_POINTER] opc
9520: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f ode is used to o
9530: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a btain a pointer.
9540: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 ** to the [sqlit
9550: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 e3_file] object
9560: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
9570: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 a particular dat
9580: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
9590: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b ion. See also [
95a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 SQLITE_FCNTL_JOU
95b0: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a RNAL_POINTER]..*
95c0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
95d0: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f E_FCNTL_JOURNAL_
95e0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 POINTER]].** The
95f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a [SQLITE_FCNTL_J
9600: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 OURNAL_POINTER]
9610: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
9620: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 o obtain a point
9630: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 er.** to the [sq
9640: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
9650: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ct associated wi
9660: 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 th the journal f
9670: 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 ile (either.** t
9680: 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 he [rollback jou
9690: 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 rnal] or the [wr
96a0: 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 ite-ahead log])
96b0: 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
96c0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
96d0: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c nection. See al
96e0: 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c so [SQLITE_FCNTL
96f0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a _FILE_POINTER]..
9700: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
9710: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d TE_FCNTL_SYNC_OM
9720: 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f ITTED]].** No lo
9730: 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a nger in use..**.
9740: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
9750: 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 FCNTL_SYNC]].**
9760: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
9770: 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 L_SYNC] opcode i
9780: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 s generated inte
9790: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 rnally by SQLite
97a0: 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 and.** sent to
97b0: 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 the VFS immediat
97c0: 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 ely before the x
97d0: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 Sync method is i
97e0: 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 nvoked on a.** d
97f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 atabase file des
9800: 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 criptor. Or, if
9810: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 the xSync method
9820: 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 is not invoked
9830: 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 .** because the
9840: 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 user has configu
9850: 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 red SQLite with
9860: 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 .** [PRAGMA sync
9870: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 hronous | PRAGMA
9880: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 synchronous=OFF
9890: 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 ] it is invoked
98a0: 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 in place .** of
98b0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 the xSync method
98c0: 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c . In most cases,
98d0: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 the pointer arg
98e0: 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 ument passed wit
98f0: 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 h.** this file-c
9900: 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 ontrol is NULL.
9910: 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 However, if the
9920: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 database file is
9930: 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a being synced.**
9940: 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 as part of a mu
9950: 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d lti-database com
9960: 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e mit, the argumen
9970: 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 t points to a nu
9980: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 l-terminated.**
9990: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e string containin
99a0: 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f g the transactio
99b0: 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 ns master-journa
99c0: 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 l file name. VFS
99d0: 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e es that .** do n
99e0: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 ot need this sig
99f0: 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e nal should silen
9a00: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 tly ignore this
9a10: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 opcode. Applicat
9a20: 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 ions .** should
9a30: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 not call [sqlite
9a40: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
9a50: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f ] with this opco
9a60: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d de as doing so m
9a70: 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 ay .** disrupt t
9a80: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 he operation of
9a90: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 the specialized
9aa0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 VFSes that do re
9ab0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a quire it. .**.*
9ac0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
9ad0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 CNTL_COMMIT_PHAS
9ae0: 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 ETWO]].** The [S
9af0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d QLITE_FCNTL_COMM
9b00: 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 IT_PHASETWO] opc
9b10: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 ode is generated
9b20: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 internally by S
9b30: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e QLite.** and sen
9b40: 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 t to the VFS aft
9b50: 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e er a transaction
9b60: 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 has been commit
9b70: 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a ted immediately.
9b80: 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 ** but before th
9b90: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e e database is un
9ba0: 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 locked. VFSes th
9bb0: 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 at do not need t
9bc0: 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 his signal.** sh
9bd0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 ould silently ig
9be0: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 nore this opcode
9bf0: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 . Applications s
9c00: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a hould not call.*
9c10: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f * [sqlite3_file_
9c20: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 control()] with
9c30: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 this opcode as d
9c40: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 oing so may disr
9c50: 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 upt the .** oper
9c60: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 ation of the spe
9c70: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 cialized VFSes t
9c80: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 hat do require i
9c90: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b t. .**.** <li>[
9ca0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 [SQLITE_FCNTL_WI
9cb0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a N32_AV_RETRY]].*
9cc0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
9cd0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 CNTL_WIN32_AV_RE
9ce0: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 TRY] opcode is u
9cf0: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 sed to configure
9d00: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 automatic.** re
9d10: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 try counts and i
9d20: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 ntervals for cer
9d30: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 tain disk I/O op
9d40: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 erations for the
9d50: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 .** windows [VFS
9d60: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 ] in order to pr
9d70: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 ovide robustness
9d80: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 in the presence
9d90: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 of.** anti-viru
9da0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 s programs. By
9db0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e default, the win
9dc0: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 dows VFS will re
9dd0: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a try file read,.*
9de0: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e * file write, an
9df0: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 d file delete op
9e00: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 erations up to 1
9e10: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 0 times, with a
9e20: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d delay.** of 25 m
9e30: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f illiseconds befo
9e40: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 re the first ret
9e50: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 ry and with the
9e60: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 delay increasing
9e70: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 .** by an additi
9e80: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 onal 25 millisec
9e90: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 onds with each s
9ea0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e ubsequent retry.
9eb0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 This.** opcode
9ec0: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 allows these tw
9ed0: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 o values (10 ret
9ee0: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c ries and 25 mill
9ef0: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 iseconds of dela
9f00: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 y).** to be adju
9f10: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 sted. The value
9f20: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f s are changed fo
9f30: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 r all database c
9f40: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 onnections.** wi
9f50: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 thin the same pr
9f60: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 ocess. The argu
9f70: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
9f80: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 r to an array of
9f90: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 two.** integers
9fa0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 where the first
9fb0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e integer i the n
9fc0: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 ew retry count a
9fd0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a nd the second.**
9fe0: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 integer is the
9ff0: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 delay. If eithe
a000: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 r integer is neg
a010: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 ative, then the
a020: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f setting.** is no
a030: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e t changed but in
a040: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 stead the prior
a050: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 value of that se
a060: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e tting is written
a070: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 .** into the arr
a080: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 ay entry, allowi
a090: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 ng the current r
a0a0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f etry settings to
a0b0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 be.** interroga
a0c0: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d ted. The zDbNam
a0d0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 e parameter is i
a0e0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c gnored..**.** <l
a0f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
a100: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a _PERSIST_WAL]].*
a110: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
a120: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c CNTL_PERSIST_WAL
a130: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
a140: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 to set or query
a150: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 the.** persiste
a160: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 nt [WAL | Write
a170: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 Ahead Log] setti
a180: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c ng. By default,
a190: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a the auxiliary.*
a1a0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f * write ahead lo
a1b0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d g and shared mem
a1c0: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 ory files used f
a1d0: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 or transaction c
a1e0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 ontrol.** are au
a1f0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 tomatically dele
a200: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 ted when the lat
a210: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 est connection t
a220: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a o the database.*
a230: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 * closes. Setti
a240: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 ng persistent WA
a250: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 L mode causes th
a260: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 ose files to per
a270: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c sist after.** cl
a280: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 ose. Persisting
a290: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 the files is us
a2a0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 eful when other
a2b0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 processes that d
a2c0: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 o not.** have wr
a2d0: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f ite permission o
a2e0: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 n the directory
a2f0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 containing the d
a300: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e atabase file wan
a310: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 t.** to read the
a320: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
a330: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 as the WAL and s
a340: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c hared memory fil
a350: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a es must exist.**
a360: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 in order for th
a370: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 e database to be
a380: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 readable. The
a390: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
a3a0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
a3b0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
a3c0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 for this opcode
a3d0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e should be a poin
a3e0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
a3f0: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 r..** That integ
a400: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 er is 0 to disab
a410: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 le persistent WA
a420: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 L mode or 1 to e
a430: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 nable persistent
a440: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 .** WAL mode. I
a450: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 f the integer is
a460: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 -1, then it is
a470: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 overwritten with
a480: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
a490: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 WAL persistence
a4a0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c setting..**.** <
a4b0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
a4c0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 L_POWERSAFE_OVER
a4d0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 WRITE]].** ^The
a4e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f [SQLITE_FCNTL_PO
a4f0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 WERSAFE_OVERWRIT
a500: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
a510: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 d to set or quer
a520: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 y the.** persist
a530: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f ent "powersafe-o
a540: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 verwrite" or "PS
a550: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 OW" setting. Th
a560: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a e PSOW setting.*
a570: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 * determines the
a580: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 [SQLITE_IOCAP_P
a590: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
a5a0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a TE] bit of the.*
a5b0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 * xDeviceCharact
a5c0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 eristics methods
a5d0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 . The fourth par
a5e0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 ameter to.** [sq
a5f0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
a600: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f ol()] for this o
a610: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 pcode should be
a620: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
a630: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 integer..** That
a640: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f integer is 0 to
a650: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 disable zero-da
a660: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 mage mode or 1 t
a670: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 o enable zero-da
a680: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 mage.** mode. I
a690: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 f the integer is
a6a0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 -1, then it is
a6b0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 overwritten with
a6c0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
a6d0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 zero-damage mode
a6e0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 setting..**.**
a6f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
a700: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a TL_OVERWRITE]].*
a710: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
a720: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 CNTL_OVERWRITE]
a730: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 opcode is invoke
a740: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 d by SQLite afte
a750: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 r opening.** a w
a760: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e rite transaction
a770: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
a780: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 t, unless it is
a790: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 rolled back for
a7a0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 some.** reason,
a7b0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 the entire datab
a7c0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 ase file will be
a7d0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 overwritten by
a7e0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 the current .**
a7f0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 transaction. Thi
a800: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 s is used by VAC
a810: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a UUM operations..
a820: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
a830: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 TE_FCNTL_VFSNAME
a840: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
a850: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 TE_FCNTL_VFSNAME
a860: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 ] opcode can be
a870: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 used to obtain t
a880: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 he names of.** a
a890: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 ll [VFSes] in th
a8a0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 e VFS stack. Th
a8b0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 e names are of a
a8c0: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 ll VFS shims and
a8d0: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f the.** final bo
a8e0: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 ttom-level VFS a
a8f0: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 re written into
a900: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
a910: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 from .** [sqlite
a920: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 3_malloc()] and
a930: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 the result is st
a940: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 ored in the char
a950: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 * variable.** th
a960: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 at the fourth pa
a970: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 rameter of [sqli
a980: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
a990: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a ()] points to..*
a9a0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 * The caller is
a9b0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 responsible for
a9c0: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f freeing the memo
a9d0: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 ry when done. A
a9e0: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 s with.** all fi
a9f0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f le-control actio
aa00: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 ns, there is no
aa10: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 guarantee that t
aa20: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c his will actuall
aa30: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 y.** do anything
aa40: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c . Callers shoul
aa50: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 d initialize the
aa60: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 char* variable
aa70: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 to a NULL.** poi
aa80: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 nter in case thi
aa90: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 s file-control i
aaa0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 s not implemente
aab0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f d. This file-co
aac0: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 ntrol.** is inte
aad0: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 nded for diagnos
aae0: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a tic use only..**
aaf0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
ab00: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 _FCNTL_VFS_POINT
ab10: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ER]].** ^The [SQ
ab20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 LITE_FCNTL_VFS_P
ab30: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 OINTER] opcode f
ab40: 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74 inds a pointer t
ab50: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a o the top-level.
ab60: 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65 ** [VFSes] curre
ab70: 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 ntly in use. ^(
ab80: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69 The argument X i
ab90: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c n.** sqlite3_fil
aba0: 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c e_control(db,SQL
abb0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f ITE_FCNTL_VFS_PO
abc0: 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65 INTER,X) must be
abd0: 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71 .** of type "[sq
abe0: 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 lite3_vfs] **".
abf0: 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69 This opcodes wi
ac00: 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 ll set *X.** to
ac10: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
ac20: 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 top-level VFS.)
ac30: 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 ^.** ^When there
ac40: 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 are multiple VF
ac50: 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73 S shims in the s
ac60: 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 tack, this opcod
ac70: 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 e finds the.** u
ac80: 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f pper-most shim o
ac90: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b nly..**.** <li>[
aca0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
acb0: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 AGMA]].** ^Whene
acc0: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 ver a [PRAGMA] s
acd0: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 tatement is pars
ace0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 ed, an [SQLITE_F
acf0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a CNTL_PRAGMA] .**
ad00: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 file control is
ad10: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 sent to the ope
ad20: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d n [sqlite3_file]
ad30: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f object correspo
ad40: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 nding.** to the
ad50: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f database file to
ad60: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d which the pragm
ad70: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 a statement refe
ad80: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e rs. ^The argumen
ad90: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c t.** to the [SQL
ada0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
adb0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 ] file control i
adc0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a s an array of.**
add0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
ade0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e ings (char**) in
adf0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e which the secon
ae00: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 d element of the
ae10: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 array.** is the
ae20: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 name of the pra
ae30: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 gma and the thir
ae40: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 d element is the
ae50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
ae60: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 .** pragma or NU
ae70: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 LL if the pragma
ae80: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 has no argument
ae90: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 . ^The handler
aea0: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 for an.** [SQLIT
aeb0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
aec0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e file control can
aed0: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 optionally make
aee0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 the first eleme
aef0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 nt.** of the cha
af00: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 r** argument poi
af10: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f nt to a string o
af20: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
af30: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d lite3_mprintf()]
af40: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 .** or the equiv
af50: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 alent and that s
af60: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d tring will becom
af70: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 e the result of
af80: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a the pragma or.**
af90: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
afa0: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 ge if the pragma
afb0: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a fails. ^If the.
afc0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [SQLITE_FCNTL
afd0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
afe0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 ntrol returns [S
aff0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c QLITE_NOTFOUND],
b000: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a then normal .**
b010: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 [PRAGMA] proces
b020: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 sing continues.
b030: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 ^If the [SQLITE
b040: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a _FCNTL_PRAGMA].*
b050: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 * file control r
b060: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
b070: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 K], then the par
b080: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 ser assumes that
b090: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 the.** VFS has
b0a0: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 handled the PRAG
b0b0: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 MA itself and th
b0c0: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 e parser generat
b0d0: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 es a no-op.** pr
b0e0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
b0f0: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e if result strin
b100: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 g is NULL, or th
b110: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 at returns a cop
b120: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 y.** of the resu
b130: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 lt string if the
b140: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e string is non-N
b150: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ULL..** ^If the
b160: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
b170: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 AGMA] file contr
b180: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e ol returns.** an
b190: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 y result code ot
b1a0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
b1b0: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f _OK] or [SQLITE_
b1c0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 NOTFOUND], that
b1d0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 means.** that th
b1e0: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 e VFS encountere
b1f0: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 d an error while
b200: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 handling the [P
b210: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a RAGMA] and the.*
b220: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 * compilation of
b230: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c the PRAGMA fail
b240: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e s with an error.
b250: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ^The [SQLITE_F
b260: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 CNTL_PRAGMA].**
b270: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 file control occ
b280: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e urs at the begin
b290: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 ning of pragma s
b2a0: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 tatement analysi
b2b0: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 s and so.** it i
b2c0: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 s able to overri
b2d0: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 de built-in [PRA
b2e0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e GMA] statements.
b2f0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
b300: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 ITE_FCNTL_BUSYHA
b310: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 NDLER]].** ^The
b320: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 [SQLITE_FCNTL_BU
b330: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 SYHANDLER].** fi
b340: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 le-control may b
b350: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c e invoked by SQL
b360: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ite on the datab
b370: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a ase file handle.
b380: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 ** shortly after
b390: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e it is opened in
b3a0: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 order to provid
b3b0: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 e a custom VFS w
b3c0: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f ith access.** to
b3d0: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 the connections
b3e0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 busy-handler ca
b3f0: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 llback. The argu
b400: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 ment is of type
b410: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 (void **).** - a
b420: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 n array of two (
b430: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 void *) values.
b440: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 The first (void
b450: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e *) actually poin
b460: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 ts.** to a funct
b470: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 ion of type (int
b480: 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 (SQLITE_CALLBAC
b490: 4b 20 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 K *)(void *)). I
b4a0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b n order to invok
b4b0: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e e the connection
b4c0: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 s.** busy-handle
b4d0: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e r, this function
b4e0: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b should be invok
b4f0: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f ed with the seco
b500: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a nd (void *) in.*
b510: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 * the array as t
b520: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 he only argument
b530: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 . If it returns
b540: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 non-zero, then t
b550: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 he operation.**
b560: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 should be retrie
b570: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 d. If it returns
b580: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f zero, the custo
b590: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 m VFS should aba
b5a0: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 ndon the.** curr
b5b0: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a ent operation..*
b5c0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
b5d0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 E_FCNTL_TEMPFILE
b5e0: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 NAME]].** ^Appli
b5f0: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b cation can invok
b600: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 e the [SQLITE_FC
b610: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 NTL_TEMPFILENAME
b620: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a ] file-control.*
b630: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 * to have SQLite
b640: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 generate a.** t
b650: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d emporary filenam
b660: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 e using the same
b670: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 algorithm that
b680: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 is followed to g
b690: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f enerate.** tempo
b6a0: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 rary filenames f
b6b0: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 or TEMP tables a
b6c0: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 nd other interna
b6d0: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 l uses. The.**
b6e0: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
b6f0: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 be a char** whic
b700: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 h will be filled
b710: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 with the filena
b720: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e me.** written in
b730: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
b740: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
b750: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 _malloc()]. The
b760: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a caller should.*
b770: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 * invoke [sqlite
b780: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 3_free()] on the
b790: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 result to avoid
b7a0: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a a memory leak..
b7b0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
b7c0: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 TE_FCNTL_MMAP_SI
b7d0: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ZE]].** The [SQL
b7e0: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 ITE_FCNTL_MMAP_S
b7f0: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f IZE] file contro
b800: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 l is used to que
b810: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a ry or set the.**
b820: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
b830: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69 of bytes that wi
b840: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d ll be used for m
b850: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f emory-mapped I/O
b860: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e ..** The argumen
b870: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
b880: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 o a value of typ
b890: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 e sqlite3_int64
b8a0: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 that.** is an ad
b8b0: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e visory maximum n
b8c0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
b8d0: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 n the file to me
b8e0: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a mory map. The.*
b8f0: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 * pointer is ove
b900: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 rwritten with th
b910: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 e old value. Th
b920: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 e limit is not c
b930: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 hanged if.** the
b940: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c value originall
b950: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 y pointed to is
b960: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f negative, and so
b970: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d the current lim
b980: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 it .** can be qu
b990: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 eried by passing
b9a0: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f in a pointer to
b9b0: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 a negative numb
b9c0: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c er. This.** fil
b9d0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 e-control is use
b9e0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 d internally to
b9f0: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d implement [PRAGM
ba00: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a A mmap_size]..**
ba10: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
ba20: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a _FCNTL_TRACE]].*
ba30: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
ba40: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 NTL_TRACE] file
ba50: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 control provides
ba60: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d advisory inform
ba70: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 ation.** to the
ba80: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 VFS about what t
ba90: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 he higher layers
baa0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 of the SQLite s
bab0: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a tack are doing..
bac0: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e ** This file con
bad0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 trol is used by
bae0: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 some VFS activit
baf0: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 y tracing [shims
bb00: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 ]..** The argume
bb10: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 nt is a zero-ter
bb20: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 minated string.
bb30: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 Higher layers i
bb40: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 n the.** SQLite
bb50: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 stack may genera
bb60: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 te instances of
bb70: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f this file contro
bb80: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c l if.** the [SQL
bb90: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 ITE_USE_FCNTL_TR
bba0: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ACE] compile-tim
bbb0: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 e option is enab
bbc0: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b led..**.** <li>[
bbd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 [SQLITE_FCNTL_HA
bbe0: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 S_MOVED]].** The
bbf0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 [SQLITE_FCNTL_H
bc00: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 AS_MOVED] file c
bc10: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 ontrol interpret
bc20: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 s its argument a
bc30: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 s a.** pointer t
bc40: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 o an integer and
bc50: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f it writes a boo
bc60: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 lean into that i
bc70: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 nteger depending
bc80: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f .** on whether o
bc90: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 r not the file h
bca0: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c as been renamed,
bcb0: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 moved, or delet
bcc0: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 ed since it.** w
bcd0: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e as first opened.
bce0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
bcf0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
bd00: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 SET_HANDLE]].**
bd10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
bd20: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 L_WIN32_SET_HAND
bd30: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 LE] opcode is us
bd40: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 ed for debugging
bd50: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
bd60: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 e causes the xFi
bd70: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
bd80: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c to swap the fil
bd90: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 e handle with th
bda0: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 e one.** pointed
bdb0: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 to by the pArg
bdc0: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 argument. This
bdd0: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 capability is us
bde0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
bdf0: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 g.** and only ne
be00: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 eds to be suppor
be10: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f ted when SQLITE_
be20: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e TEST is defined.
be30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
be40: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c ITE_FCNTL_WAL_BL
be50: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 OCK]].** The [SQ
be60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 LITE_FCNTL_WAL_B
be70: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 LOCK] is a signa
be80: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 l to the VFS lay
be90: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 er that it might
bea0: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 .** be advantage
beb0: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 ous to block on
bec0: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 the next WAL loc
bed0: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 k if the lock is
bee0: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 not immediately
bef0: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 .** available.
bf00: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 The WAL subsyste
bf10: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69 m issues this si
bf20: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 gnal during rare
bf30: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 .** circumstance
bf40: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 s in order to fi
bf50: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 x a problem with
bf60: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 priority invers
bf70: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ion..** Applicat
bf80: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e ions should <em>
bf90: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 not</em> use thi
bfa0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a s file-control..
bfb0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
bfc0: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d TE_FCNTL_ZIPVFS]
bfd0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
bfe0: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f _FCNTL_ZIPVFS] o
bff0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 pcode is impleme
c000: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f nted by zipvfs o
c010: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a nly. All other.*
c020: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 * VFS should ret
c030: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f urn SQLITE_NOTFO
c040: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 UND for this opc
c050: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ode..**.** <li>[
c060: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 [SQLITE_FCNTL_RB
c070: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 U]].** The [SQLI
c080: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 TE_FCNTL_RBU] op
c090: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e code is implemen
c0a0: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69 ted by the speci
c0b0: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a al VFS used by.*
c0c0: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73 * the RBU extens
c0d0: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f ion only. All o
c0e0: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 ther VFS should
c0f0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f return SQLITE_NO
c100: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 TFOUND for.** th
c110: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 is opcode. .**
c120: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </ul>.*/.#define
c130: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f SQLITE_FCNTL_LO
c140: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 CKSTATE
c150: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
c160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 SQLITE_FCNTL_GET
c170: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
c180: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
c190: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f QLITE_FCNTL_SET_
c1a0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 LOCKPROXYFILE
c1b0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
c1c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f LITE_FCNTL_LAST_
c1d0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 ERRNO
c1e0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
c1f0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 ITE_FCNTL_SIZE_H
c200: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 INT
c210: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 5.#define SQLI
c220: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 TE_FCNTL_CHUNK_S
c230: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 IZE
c240: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
c250: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 E_FCNTL_FILE_POI
c260: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 NTER
c270: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 7.#define SQLITE
c280: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 _FCNTL_SYNC_OMIT
c290: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 TED 8
c2a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c2b0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 FCNTL_WIN32_AV_R
c2c0: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a ETRY 9.
c2d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
c2e0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c CNTL_PERSIST_WAL
c2f0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 10.#
c300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
c310: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 NTL_OVERWRITE
c320: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 11.#d
c330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
c340: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 TL_VFSNAME
c350: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 12.#de
c360: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
c370: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 L_POWERSAFE_OVER
c380: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 WRITE 13.#def
c390: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
c3a0: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 _PRAGMA
c3b0: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 14.#defi
c3c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
c3d0: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 BUSYHANDLER
c3e0: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 15.#defin
c3f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 e SQLITE_FCNTL_T
c400: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 EMPFILENAME
c410: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 16.#define
c420: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d SQLITE_FCNTL_MM
c430: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 AP_SIZE
c440: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 18.#define
c450: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 SQLITE_FCNTL_TRA
c460: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CE
c470: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 19.#define S
c480: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f QLITE_FCNTL_HAS_
c490: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20 MOVED
c4a0: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 20.#define SQ
c4b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 LITE_FCNTL_SYNC
c4c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
c4d0: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 21.#define SQL
c4e0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 ITE_FCNTL_COMMIT
c4f0: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 _PHASETWO
c500: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 22.#define SQLI
c510: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 TE_FCNTL_WIN32_S
c520: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 ET_HANDLE
c530: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 23.#define SQLIT
c540: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 E_FCNTL_WAL_BLOC
c550: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 K 2
c560: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
c570: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 _FCNTL_ZIPVFS
c580: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 25
c590: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c5a0: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20 FCNTL_RBU
c5b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 26.
c5c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
c5d0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 CNTL_VFS_POINTER
c5e0: 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a 23 27.#
c5f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
c600: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e NTL_JOURNAL_POIN
c610: 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 0a 2f TER 28../
c620: 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d * deprecated nam
c630: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 es */.#define SQ
c640: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f LITE_GET_LOCKPRO
c650: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 XYFILE SQLI
c660: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 TE_FCNTL_GET_LOC
c670: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 KPROXYFILE.#defi
c680: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f ne SQLITE_SET_LO
c690: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 CKPROXYFILE
c6a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 SQLITE_FCNTL_SE
c6b0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a T_LOCKPROXYFILE.
c6c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
c6d0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 AST_ERRNO
c6e0: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e SQLITE_FCN
c6f0: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a TL_LAST_ERRNO...
c700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
c710: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a Mutex Handle.**.
c720: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 ** The mutex mod
c730: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 ule within SQLit
c740: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 e defines [sqlit
c750: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 e3_mutex] to be
c760: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 an.** abstract t
c770: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 ype for a mutex
c780: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c object. The SQL
c790: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c ite core never l
c7a0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 ooks.** at the i
c7b0: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e nternal represen
c7c0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 tation of an [sq
c7d0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 lite3_mutex]. I
c7e0: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 t only.** deals
c7f0: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f with pointers to
c800: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
c810: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a tex] object..**.
c820: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 ** Mutexes are c
c830: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 reated using [sq
c840: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
c850: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 c()]..*/.typedef
c860: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
c870: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 mutex sqlite3_mu
c880: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 tex;../*.** CAPI
c890: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 3REF: OS Interfa
c8a0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 ce Object.**.**
c8b0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
c8c0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f he sqlite3_vfs o
c8d0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 bject defines th
c8e0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 e interface betw
c8f0: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 een.** the SQLit
c900: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 e core and the u
c910: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 nderlying operat
c920: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 ing system. The
c930: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 "vfs".** in the
c940: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a name of the obj
c950: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 ect stands for "
c960: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 virtual file sys
c970: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 tem". See.** th
c980: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 e [VFS | VFS doc
c990: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 umentation] for
c9a0: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 further informat
c9b0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 ion..**.** The v
c9c0: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 alue of the iVer
c9d0: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e sion field is in
c9e0: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 itially 1 but ma
c9f0: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a y be larger in.*
ca00: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e * future version
ca10: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 s of SQLite. Ad
ca20: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 ditional fields
ca30: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 may be appended
ca40: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 to this.** objec
ca50: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 t when the iVers
ca60: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 ion value is inc
ca70: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 reased. Note th
ca80: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 at the structure
ca90: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 .** of the sqlit
caa0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 e3_vfs object ch
cab0: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 anges in the tra
cac0: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e nsaction between
cad0: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 .** SQLite versi
cae0: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 on 3.5.9 and 3.6
caf0: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 .0 and yet the i
cb00: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 Version field wa
cb10: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 s not.** modifie
cb20: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f d..**.** The szO
cb30: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 sFile field is t
cb40: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 he size of the s
cb50: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 ubclassed [sqlit
cb60: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 e3_file].** stru
cb70: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 cture used by th
cb80: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e is VFS. mxPathn
cb90: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d ame is the maxim
cba0: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 um length of.**
cbb0: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 a pathname in th
cbc0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 is VFS..**.** Re
cbd0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 gistered sqlite3
cbe0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 _vfs objects are
cbf0: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 kept on a linke
cc00: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 d list formed by
cc10: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f .** the pNext po
cc20: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c inter. The [sql
cc30: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 ite3_vfs_registe
cc40: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c r()].** and [sql
cc50: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 ite3_vfs_unregis
cc60: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ter()] interface
cc70: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 s manage this li
cc80: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 st.** in a threa
cc90: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 d-safe way. The
cca0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 [sqlite3_vfs_fi
ccb0: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a nd()] interface.
ccc0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 ** searches the
ccd0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 list. Neither t
cce0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 he application c
ccf0: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a ode nor the VFS.
cd00: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
cd10: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 n should use the
cd20: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a pNext pointer..
cd30: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 **.** The pNext
cd40: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c field is the onl
cd50: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 y field in the s
cd60: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 qlite3_vfs.** st
cd70: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c ructure that SQL
cd80: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f ite will ever mo
cd90: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 dify. SQLite wi
cda0: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a ll only access.*
cdb0: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 * or modify this
cdc0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c field while hol
cdd0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 ding a particula
cde0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a r static mutex..
cdf0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
ce00: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 on should never
ce10: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 modify anything
ce20: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 within the sqlit
ce30: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 e3_vfs.** object
ce40: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 once the object
ce50: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 has been regist
ce60: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ered..**.** The
ce70: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 zName field hold
ce80: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
ce90: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 e VFS module. T
cea0: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 he name must.**
ceb0: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 be unique across
cec0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 all VFS modules
ced0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 ..**.** [[sqlite
cee0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 3_vfs.xOpen]].**
cef0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 ^SQLite guarant
cf00: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 ees that the zFi
cf10: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
cf20: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 to xOpen.** is
cf30: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f either a NULL po
cf40: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 inter or string
cf50: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d obtained.** from
cf60: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 xFullPathname()
cf70: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 with an optiona
cf80: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a l suffix added..
cf90: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 ** ^If a suffix
cfa0: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 is added to the
cfb0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 zFilename parame
cfc0: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 ter, it will.**
cfd0: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e consist of a sin
cfe0: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 gle "-" characte
cff0: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f r followed by no
d000: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 more than.** 11
d010: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e alphanumeric an
d020: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 d/or "-" charact
d030: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ers..** ^SQLite
d040: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 further guarante
d050: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 es that.** the s
d060: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 tring will be va
d070: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 lid and unchange
d080: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 d until xClose()
d090: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 is.** called. B
d0a0: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 ecause of the pr
d0b0: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c evious sentence,
d0c0: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
d0d0: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c _file] can safel
d0e0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 y store a pointe
d0f0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 r to the.** file
d100: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 name if it needs
d110: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 to remember the
d120: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f filename for so
d130: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 me reason..** If
d140: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 the zFilename p
d150: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 arameter to xOpe
d160: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e n is a NULL poin
d170: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a ter then xOpen.*
d180: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 * must invent it
d190: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 s own temporary
d1a0: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c name for the fil
d1b0: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 e. ^Whenever th
d1c0: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 e .** xFilename
d1d0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c parameter is NUL
d1e0: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 L it will also b
d1f0: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 e the case that
d200: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 the.** flags par
d210: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c ameter will incl
d220: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ude [SQLITE_OPEN
d230: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e _DELETEONCLOSE].
d240: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 .**.** The flags
d250: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 argument to xOp
d260: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c en() includes al
d270: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a l bits set in.**
d280: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d the flags argum
d290: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ent to [sqlite3_
d2a0: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 open_v2()]. Or
d2b0: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e if [sqlite3_open
d2c0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 ()].** or [sqlit
d2d0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 e3_open16()] is
d2e0: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 used, then flags
d2f0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 includes at lea
d300: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 st.** [SQLITE_OP
d310: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 EN_READWRITE] |
d320: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
d330: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 ATE]. .** If xOp
d340: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c en() opens a fil
d350: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e e read-only then
d360: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c it sets *pOutFl
d370: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 ags to.** includ
d380: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 e [SQLITE_OPEN_R
d390: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 EADONLY]. Other
d3a0: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c bits in *pOutFl
d3b0: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a ags may be set..
d3c0: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 **.** ^(SQLite w
d3d0: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 ill also add one
d3e0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
d3f0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 g flags to the x
d400: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 Open().** call,
d410: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
d420: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 object being op
d430: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ened:.**.** <ul>
d440: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
d450: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a E_OPEN_MAIN_DB].
d460: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
d470: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e _OPEN_MAIN_JOURN
d480: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
d490: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 LITE_OPEN_TEMP_D
d4a0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c B].** <li> [SQL
d4b0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f ITE_OPEN_TEMP_JO
d4c0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
d4d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 [SQLITE_OPEN_TRA
d4e0: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c NSIENT_DB].** <l
d4f0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
d500: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 _SUBJOURNAL].**
d510: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
d520: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 EN_MASTER_JOURNA
d530: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
d540: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a ITE_OPEN_WAL].**
d550: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 </ul>)^.**.** T
d560: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c he file I/O impl
d570: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 ementation can u
d580: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 se the object ty
d590: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 pe flags to.** c
d5a0: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 hange the way it
d5b0: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 deals with file
d5c0: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c s. For example,
d5d0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a an application.
d5e0: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 ** that does not
d5f0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 care about cras
d600: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f h recovery or ro
d610: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b llback might mak
d620: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 e.** the open of
d630: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 a journal file
d640: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 a no-op. Writes
d650: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c to this journal
d660: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 would.** also b
d670: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e e no-ops, and an
d680: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 y attempt to rea
d690: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f d the journal wo
d6a0: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 uld return.** SQ
d6b0: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 LITE_IOERR. Or
d6c0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
d6d0: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 on might recogni
d6e0: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 ze that a databa
d6f0: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 se.** file will
d700: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c be doing page-al
d710: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 igned sector rea
d720: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e ds and writes in
d730: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 a random.** ord
d740: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 er and set up it
d750: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 s I/O subsystem
d760: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a accordingly..**.
d770: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 ** SQLite might
d780: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 also add one of
d790: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c the following fl
d7a0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e ags to the xOpen
d7b0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c method:.**.** <
d7c0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
d7d0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
d7e0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 NCLOSE].** <li>
d7f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
d800: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e LUSIVE].** </ul>
d810: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
d820: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
d830: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e CLOSE] flag mean
d840: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c s the file shoul
d850: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 d be.** deleted
d860: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 when it is close
d870: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 d. ^The [SQLITE
d880: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
d890: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 OSE].** will be
d8a0: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 set for TEMP dat
d8b0: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 abases and their
d8c0: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 journals, trans
d8d0: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 ient.** database
d8e0: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 s, and subjourna
d8f0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b ls..**.** ^The [
d900: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
d910: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 USIVE] flag is a
d920: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f lways used in co
d930: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 njunction.** wit
d940: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 h the [SQLITE_OP
d950: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c EN_CREATE] flag,
d960: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 which are both
d970: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c directly.** anal
d980: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 ogous to the O_E
d990: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 XCL and O_CREAT
d9a0: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 flags of the POS
d9b0: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 IX open().** API
d9c0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 . The SQLITE_OP
d9d0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 EN_EXCLUSIVE fla
d9e0: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 g, when paired w
d9f0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 ith the .** SQLI
da00: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 TE_OPEN_CREATE,
da10: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 is used to indic
da20: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 ate that file sh
da30: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 ould always.** b
da40: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 e created, and t
da50: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 hat it is an err
da60: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 or if it already
da70: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 exists..** It i
da80: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 s <i>not</i> use
da90: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 d to indicate th
daa0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 e file should be
dab0: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 opened .** for
dac0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 exclusive access
dad0: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 ..**.** ^At leas
dae0: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 t szOsFile bytes
daf0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 of memory are a
db00: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 llocated by SQLi
db10: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 te.** to hold th
db20: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 e [sqlite3_file
db30: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 ] structure pass
db40: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a ed as the third.
db50: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 ** argument to x
db60: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e Open. The xOpen
db70: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 method does not
db80: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f have to.** allo
db90: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 cate the structu
dba0: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 re; it should ju
dbb0: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 st fill it in.
dbc0: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 Note that.** the
dbd0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 xOpen method mu
dbe0: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 st set the sqlit
dbf0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 e3_file.pMethods
dc00: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 to either.** a
dc10: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 valid [sqlite3_i
dc20: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
dc30: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 t or to NULL. x
dc40: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 Open must do.**
dc50: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 this even if the
dc60: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 open fails. SQ
dc70: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 Lite expects tha
dc80: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 t the sqlite3_fi
dc90: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 le.pMethods.** e
dca0: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 lement will be v
dcb0: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e alid after xOpen
dcc0: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c returns regardl
dcd0: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 ess of the succe
dce0: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 ss.** or failure
dcf0: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 of the xOpen ca
dd00: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 ll..**.** [[sqli
dd10: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d te3_vfs.xAccess]
dd20: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 ].** ^The flags
dd30: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 argument to xAcc
dd40: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 ess() may be [SQ
dd50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
dd60: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 TS].** to test f
dd70: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 or the existence
dd80: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b of a file, or [
dd90: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
dda0: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 ADWRITE] to.** t
ddb0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 est whether a fi
ddc0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 le is readable a
ddd0: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 nd writable, or
dde0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
ddf0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 EAD].** to test
de00: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 whether a file i
de10: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 s at least reada
de20: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 ble. The file
de30: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 can be a.** dire
de40: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 ctory..**.** ^SQ
de50: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 Lite will always
de60: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 allocate at lea
de70: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 st mxPathname+1
de80: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a bytes for the.**
de90: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 output buffer x
dea0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 FullPathname. T
deb0: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 he exact size of
dec0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 the output buff
ded0: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 er.** is also pa
dee0: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 ssed as a parame
def0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 ter to both met
df00: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 hods. If the out
df10: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 put buffer.** is
df20: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 not large enoug
df30: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f h, [SQLITE_CANTO
df40: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 PEN] should be r
df50: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 eturned. Since t
df60: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 his is.** handle
df70: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 d as a fatal err
df80: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 or by SQLite, vf
df90: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
dfa0: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f s should endeavo
dfb0: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 r.** to prevent
dfc0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 this by setting
dfd0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 mxPathname to a
dfe0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 sufficiently lar
dff0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 ge value..**.**
e000: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 The xRandomness(
e010: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 ), xSleep(), xCu
e020: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 rrentTime(), and
e030: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 xCurrentTimeInt
e040: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 64().** interfac
e050: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 es are not stric
e060: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 tly a part of th
e070: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 e filesystem, bu
e080: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e t they are.** in
e090: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 cluded in the VF
e0a0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 S structure for
e0b0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a completeness..**
e0c0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
e0d0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 () function atte
e0e0: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e mpts to return n
e0f0: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f Bytes bytes.** o
e100: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 f good-quality r
e110: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a andomness into z
e120: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e Out. The return
e130: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 value is.** the
e140: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f actual number o
e150: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f f bytes of rando
e160: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a mness obtained..
e170: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 ** The xSleep()
e180: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 method causes th
e190: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 e calling thread
e1a0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 to sleep for at
e1b0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 .** least the nu
e1c0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 mber of microsec
e1d0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 onds given. ^Th
e1e0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 e xCurrentTime()
e1f0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 .** method retur
e200: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 ns a Julian Day
e210: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 Number for the c
e220: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 urrent date and
e230: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f time as.** a flo
e240: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 ating point valu
e250: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 e..** ^The xCurr
e260: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d entTimeInt64() m
e270: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 ethod returns, a
e280: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 s an integer, th
e290: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 e Julian.** Day
e2a0: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 Number multiplie
e2b0: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 d by 86400000 (t
e2c0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c he number of mil
e2d0: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a liseconds in .**
e2e0: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e a 24-hour day).
e2f0: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 .** ^SQLite wi
e300: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 ll use the xCurr
e310: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d entTimeInt64() m
e320: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 ethod to get the
e330: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 current.** date
e340: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 and time if tha
e350: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 t method is avai
e360: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 lable (if iVersi
e370: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 on is 2 or .** g
e380: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 reater and the f
e390: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 unction pointer
e3a0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 is not NULL) and
e3b0: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a will fall back.
e3c0: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 ** to xCurrentTi
e3d0: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 me() if xCurrent
e3e0: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 TimeInt64() is u
e3f0: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a navailable..**.*
e400: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 * ^The xSetSyste
e410: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 mCall(), xGetSys
e420: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 temCall(), and x
e430: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 NestSystemCall()
e440: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 interfaces.** a
e450: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 re not used by t
e460: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 he SQLite core.
e470: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 These optional
e480: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 interfaces are p
e490: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f rovided.** by so
e4a0: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 me VFSes to faci
e4b0: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f litate testing o
e4c0: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 f the VFS code.
e4d0: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a By overriding .*
e4e0: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 * system calls w
e4f0: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e ith functions un
e500: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c der its control,
e510: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 a test program
e520: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 can.** simulate
e530: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 faults and error
e540: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 conditions that
e550: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 would otherwise
e560: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a be difficult.**
e570: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 or impossible t
e580: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 o induce. The s
e590: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c et of system cal
e5a0: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f ls that can be o
e5b0: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 verridden.** var
e5c0: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 ies from one VFS
e5d0: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 to another, and
e5e0: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f from one versio
e5f0: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 n of the same VF
e600: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 S to the.** next
e610: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 . Applications
e620: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 that use these i
e630: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 nterfaces must b
e640: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 e prepared for a
e650: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 ny.** or all of
e660: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
e670: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 to be NULL or f
e680: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f or their behavio
e690: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 r to change.** f
e6a0: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 rom one release
e6b0: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 to the next. Ap
e6c0: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 plications must
e6d0: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 not attempt to a
e6e0: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 ccess.** any of
e6f0: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 these methods if
e700: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 the iVersion of
e710: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 the VFS is less
e720: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 than 3..*/.type
e730: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
e740: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 e3_vfs sqlite3_v
e750: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 fs;.typedef void
e760: 20 28 53 51 4c 49 54 45 5f 53 59 53 41 50 49 20 (SQLITE_SYSAPI
e770: 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c *sqlite3_syscall
e780: 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 _ptr)(void);.str
e790: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 uct sqlite3_vfs
e7a0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e {. int iVersion
e7b0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ; /*
e7c0: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f Structure versio
e7d0: 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e n number (curren
e7e0: 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 tly 3) */. int
e7f0: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 szOsFile;
e800: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 /* Size of
e810: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 subclassed sqlit
e820: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 e3_file */. int
e830: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 mxPathname;
e840: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
e850: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c file pathname l
e860: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 ength */. sqlit
e870: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 e3_vfs *pNext;
e880: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 /* Next regi
e890: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 stered VFS */.
e8a0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
e8b0: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 e; /* Name
e8c0: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c of this virtual
e8d0: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a file system */.
e8e0: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 void *pAppData
e8f0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f ; /* Po
e900: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 inter to applica
e910: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 tion-specific da
e920: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 53 51 4c ta */. int (SQL
e930: 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 4f ITE_CALLBACK *xO
e940: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 pen)(sqlite3_vfs
e950: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
e960: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 Name, sqlite3_fi
e970: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 le*,.
e980: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 int flags, i
e990: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a nt *pOutFlags);.
e9a0: 20 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 41 int (SQLITE_CA
e9b0: 4c 4c 42 41 43 4b 20 2a 78 44 65 6c 65 74 65 29 LLBACK *xDelete)
e9c0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
e9d0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
e9e0: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a , int syncDir);.
e9f0: 20 20 69 6e 74 20 28 53 51 4c 49 54 45 5f 43 41 int (SQLITE_CA
ea00: 4c 4c 42 41 43 4b 20 2a 78 41 63 63 65 73 73 29 LLBACK *xAccess)
ea10: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
ea20: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
ea30: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 , int flags, int
ea40: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e *pResOut);. in
ea50: 74 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 t (SQLITE_CALLBA
ea60: 43 4b 20 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d CK *xFullPathnam
ea70: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
ea80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
ea90: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 me, int nOut, ch
eaa0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 ar *zOut);. voi
eab0: 64 20 2a 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 d *(SQLITE_CALLB
eac0: 41 43 4b 20 2a 78 44 6c 4f 70 65 6e 29 28 73 71 ACK *xDlOpen)(sq
ead0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
eae0: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d t char *zFilenam
eaf0: 65 29 3b 0a 20 20 76 6f 69 64 20 28 53 51 4c 49 e);. void (SQLI
eb00: 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 44 6c TE_CALLBACK *xDl
eb10: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 Error)(sqlite3_v
eb20: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 fs*, int nByte,
eb30: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a char *zErrMsg);.
eb40: 20 20 76 6f 69 64 20 28 53 51 4c 49 54 45 5f 43 void (SQLITE_C
eb50: 41 4c 4c 42 41 43 4b 20 2a 28 2a 78 44 6c 53 79 ALLBACK *(*xDlSy
eb60: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c m)(sqlite3_vfs*,
eb70: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 void*, const cha
eb80: 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 r *zSymbol))(voi
eb90: 64 29 3b 0a 20 20 76 6f 69 64 20 28 53 51 4c 49 d);. void (SQLI
eba0: 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 44 6c TE_CALLBACK *xDl
ebb0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 Close)(sqlite3_v
ebc0: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 fs*, void*);. i
ebd0: 6e 74 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 nt (SQLITE_CALLB
ebe0: 41 43 4b 20 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 ACK *xRandomness
ebf0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
ec00: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 int nByte, char
ec10: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 53 *zOut);. int (S
ec20: 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a QLITE_CALLBACK *
ec30: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f xSleep)(sqlite3_
ec40: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 vfs*, int micros
ec50: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 econds);. int (
ec60: 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 SQLITE_CALLBACK
ec70: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 *xCurrentTime)(s
ec80: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 qlite3_vfs*, dou
ec90: 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 53 51 ble*);. int (SQ
eca0: 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 LITE_CALLBACK *x
ecb0: 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 GetLastError)(sq
ecc0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c lite3_vfs*, int,
ecd0: 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 char *);. /*.
ece0: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 ** The methods
ecf0: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 above are in ver
ed00: 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 sion 1 of the sq
ed10: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a lite_vfs object.
ed20: 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e ** definition.
ed30: 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c Those that fol
ed40: 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e low are added in
ed50: 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 version 2 or la
ed60: 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 ter. */. int (
ed70: 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 SQLITE_CALLBACK
ed80: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 *xCurrentTimeInt
ed90: 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 64)(sqlite3_vfs*
eda0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a , sqlite3_int64*
edb0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 );. /*. ** The
edc0: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 methods above a
edd0: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 re in versions 1
ede0: 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 and 2 of the sq
edf0: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e lite_vfs object.
ee00: 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f . ** Those belo
ee10: 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f w are for versio
ee20: 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e n 3 and greater.
ee30: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 53 51 4c . */. int (SQL
ee40: 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 53 ITE_CALLBACK *xS
ee50: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 etSystemCall)(sq
ee60: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
ee70: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 t char *zName, s
ee80: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 qlite3_syscall_p
ee90: 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 tr);. sqlite3_s
eea0: 79 73 63 61 6c 6c 5f 70 74 72 20 28 53 51 4c 49 yscall_ptr (SQLI
eeb0: 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 47 65 TE_CALLBACK *xGe
eec0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c tSystemCall)(sql
eed0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
eee0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 char *zName);.
eef0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 53 51 const char *(SQ
ef00: 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 LITE_CALLBACK *x
ef10: 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 NextSystemCall)(
ef20: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
ef30: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 nst char *zName)
ef40: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 ;. /*. ** The
ef50: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 methods above ar
ef60: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 e in versions 1
ef70: 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 through 3 of the
ef80: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
ef90: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 ct.. ** New fie
efa0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e lds may be appen
efb0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 ded in future ve
efc0: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 rsions. The iVe
efd0: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 rsion. ** value
efe0: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 will increment
eff0: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 whenever this ha
f000: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a ppens. . */.};.
f010: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
f020: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 Flags for the x
f030: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f Access VFS metho
f040: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e d.**.** These in
f050: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
f060: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 can be used as t
f070: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
f080: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 er to.** the xAc
f090: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 cess method of a
f0a0: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 n [sqlite3_vfs]
f0b0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 object. They de
f0c0: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 termine.** what
f0d0: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 kind of permissi
f0e0: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 ons the xAccess
f0f0: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e method is lookin
f100: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 g for..** With S
f110: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
f120: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 STS, the xAccess
f130: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c method.** simpl
f140: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 y checks whether
f150: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 the file exists
f160: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 ..** With SQLITE
f170: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
f180: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d E, the xAccess m
f190: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 ethod.** checks
f1a0: 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 whether the name
f1b0: 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 d directory is b
f1c0: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 oth readable and
f1d0: 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e writable.** (in
f1e0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 other words, if
f1f0: 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 files can be ad
f200: 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e ded, removed, an
f210: 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e d renamed within
f220: 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 .** the director
f230: 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 y)..** The SQLIT
f240: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 E_ACCESS_READWRI
f250: 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 TE constant is c
f260: 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e urrently used on
f270: 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 ly by the.** [te
f280: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f mp_store_directo
f290: 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 ry pragma], thou
f2a0: 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 gh this could ch
f2b0: 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 ange in a future
f2c0: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 .** release of S
f2d0: 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 QLite..** With S
f2e0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
f2f0: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d D, the xAccess m
f300: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 ethod.** checks
f310: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 whether the file
f320: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 is readable. T
f330: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 he SQLITE_ACCESS
f340: 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 _READ constant i
f350: 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 s.** currently u
f360: 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 nused, though it
f370: 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 might be used i
f380: 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 n a future relea
f390: 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e se of.** SQLite.
f3a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
f3b0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 TE_ACCESS_EXISTS
f3c0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
f3d0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
f3e0: 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 WRITE 1 /* Use
f3f0: 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 d by PRAGMA temp
f400: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 _store_directory
f410: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
f420: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 TE_ACCESS_READ
f430: 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 2 /* Unuse
f440: 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d */../*.** CAPI
f450: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 3REF: Flags for
f460: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 the xShmLock VFS
f470: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 method.**.** Th
f480: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 ese integer cons
f490: 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 tants define the
f4a0: 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 various locking
f4b0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 operations.** a
f4c0: 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 llowed by the xS
f4d0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 hmLock method of
f4e0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
f4f0: 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 hods]. The.** f
f500: 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 ollowing are the
f510: 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 only legal comb
f520: 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 inations of flag
f530: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d s to the.** xShm
f540: 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a Lock method:.**.
f550: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
f560: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b SQLITE_SHM_LOCK
f570: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 | SQLITE_SHM_SH
f580: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 ARED.** <li> SQ
f590: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 LITE_SHM_LOCK |
f5a0: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 SQLITE_SHM_EXCLU
f5b0: 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 SIVE.** <li> SQ
f5c0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 LITE_SHM_UNLOCK
f5d0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 | SQLITE_SHM_SHA
f5e0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c RED.** <li> SQL
f5f0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c ITE_SHM_UNLOCK |
f600: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c SQLITE_SHM_EXCL
f610: 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a USIVE.** </ul>.*
f620: 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b *.** When unlock
f630: 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 ing, the same SH
f640: 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 ARED or EXCLUSIV
f650: 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 E flag must be s
f660: 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 upplied as.** wa
f670: 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 s given on the c
f680: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 orresponding loc
f690: 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 k. .**.** The x
f6a0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 ShmLock method c
f6b0: 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 an transition be
f6c0: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 tween unlocked a
f6d0: 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 nd SHARED or.**
f6e0: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 between unlocked
f6f0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 and EXCLUSIVE.
f700: 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 It cannot trans
f710: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 ition between SH
f720: 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c ARED.** and EXCL
f730: 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e USIVE..*/.#defin
f740: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c e SQLITE_SHM_UNL
f750: 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 OCK 1.#def
f760: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c ine SQLITE_SHM_L
f770: 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 OCK 2.#d
f780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
f790: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a _SHARED 4.
f7a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
f7b0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 HM_EXCLUSIVE
f7c0: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 8../*.** CAPI3RE
f7d0: 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c F: Maximum xShmL
f7e0: 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 ock index.**.**
f7f0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 The xShmLock met
f800: 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f hod on [sqlite3_
f810: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 io_methods] may
f820: 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 use values.** be
f830: 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 tween 0 and this
f840: 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 upper bound as
f850: 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 its "offset" arg
f860: 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 ument..** The SQ
f870: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e Lite core will n
f880: 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 ever attempt to
f890: 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 acquire or relea
f8a0: 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 se a.** lock out
f8b0: 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e side of this ran
f8c0: 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ge.*/.#define SQ
f8d0: 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 LITE_SHM_NLOCK
f8e0: 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 8.../*.**
f8f0: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 CAPI3REF: Initia
f900: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 lize The SQLite
f910: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 Library.**.** ^T
f920: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 he sqlite3_initi
f930: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 alize() routine
f940: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a initializes the.
f950: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 ** SQLite librar
f960: 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 y. ^The sqlite3
f970: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 _shutdown() rout
f980: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 ine.** deallocat
f990: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 es any resources
f9a0: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 that were alloc
f9b0: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ated by sqlite3_
f9c0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a initialize()..**
f9d0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
f9e0: 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 are designed to
f9f0: 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 aid in process i
fa00: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e nitialization an
fa10: 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e d.** shutdown on
fa20: 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d embedded system
fa30: 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 s. Workstation
fa40: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 applications usi
fa50: 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 ng.** SQLite nor
fa60: 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 mally do not nee
fa70: 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 d to invoke eith
fa80: 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 er of these rout
fa90: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 ines..**.** A ca
faa0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ll to sqlite3_in
fab0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e itialize() is an
fac0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c "effective" cal
fad0: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 l if it is.** th
fae0: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c e first time sql
faf0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
fb00: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 ) is invoked dur
fb10: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 ing the lifetime
fb20: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 of.** the proce
fb30: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 ss, or if it is
fb40: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 the first time s
fb50: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
fb60: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
fb70: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 * following a ca
fb80: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
fb90: 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c utdown(). ^(Onl
fba0: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 y an effective c
fbb0: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 all.** of sqlite
fbc0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 3_initialize() d
fbd0: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 oes any initiali
fbe0: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 zation. All oth
fbf0: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 er calls.** are
fc00: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e harmless no-ops.
fc10: 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 )^.**.** A call
fc20: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 to sqlite3_shutd
fc30: 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 own() is an "eff
fc40: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 ective" call if
fc50: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a it is the first.
fc60: 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ** call to sqlit
fc70: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 e3_shutdown() si
fc80: 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c nce the last sql
fc90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
fca0: 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e ). ^(Only.** an
fcb0: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 effective call
fcc0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 to sqlite3_shutd
fcd0: 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 own() does any d
fce0: 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e einitialization.
fcf0: 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 .** All other va
fd00: 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c lid calls to sql
fd10: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
fd20: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d are harmless no-
fd30: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ops.)^.**.** The
fd40: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
fd50: 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ize() interface
fd60: 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 is threadsafe, b
fd70: 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 ut sqlite3_shutd
fd80: 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e own().** is not.
fd90: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 The sqlite3_sh
fda0: 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 utdown() interfa
fdb0: 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 ce must only be
fdc0: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a called from a.**
fdd0: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 single thread.
fde0: 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 All open [datab
fdf0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
fe00: 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 must be closed
fe10: 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 and all.** other
fe20: 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 SQLite resource
fe30: 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f s must be deallo
fe40: 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 cated prior to i
fe50: 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 nvoking.** sqlit
fe60: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a e3_shutdown()..*
fe70: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 *.** Among other
fe80: 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 things, ^sqlite
fe90: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 3_initialize() w
fea0: 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 ill invoke.** sq
feb0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e lite3_os_init().
fec0: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 Similarly, ^sq
fed0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
fee0: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 .** will invoke
fef0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
ff00: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
ff10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
ff20: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
ff30: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e s [SQLITE_OK] on
ff40: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 success..** ^If
ff50: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e for some reason
ff60: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 , sqlite3_initia
ff70: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 lize() is unable
ff80: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a to initialize.*
ff90: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 * the library (p
ffa0: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 erhaps it is una
ffb0: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ble to allocate
ffc0: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 a needed resourc
ffd0: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d e such.** as a m
ffe0: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 utex) it returns
fff0: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
10000 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
10010 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e ITE_OK]..**.** ^
10020 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
10030 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 ialize() routine
10040 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 is called inter
10050 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 nally by many ot
10060 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e her.** SQLite in
10070 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 terfaces so that
10080 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
10090 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 usually does not
100a0 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f need to.** invo
100b0 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ke sqlite3_initi
100c0 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 alize() directly
100d0 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 . For example,
100e0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
100f0 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 .** calls sqlite
10100 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 3_initialize() s
10110 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 o the SQLite lib
10120 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 rary will be aut
10130 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e omatically.** in
10140 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b itialized when [
10150 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 sqlite3_open()]
10160 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 is called if it
10170 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 has not be initi
10180 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 alized.** alread
10190 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 y. ^However, if
101a0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
101b0 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 led with the [SQ
101c0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e LITE_OMIT_AUTOIN
101d0 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 IT].** compile-t
101e0 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e ime option, then
101f0 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 the automatic c
10200 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
10210 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 initialize().**
10220 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 are omitted and
10230 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
10240 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 must call sqlite
10250 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 3_initialize() d
10260 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 irectly.** prior
10270 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 to using any ot
10280 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
10290 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d face. For maxim
102a0 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a um portability,.
102b0 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 ** it is recomme
102c0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 nded that applic
102d0 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e ations always in
102e0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 voke sqlite3_ini
102f0 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 tialize().** dir
10300 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 ectly prior to u
10310 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 sing any other S
10320 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
10330 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 Future release
10340 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d s.** of SQLite m
10350 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e ay require this.
10360 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
10370 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 , the behavior e
10380 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e xhibited.** when
10390 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
103a0 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 led with [SQLITE
103b0 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 _OMIT_AUTOINIT]
103c0 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 might become the
103d0 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 .** default beha
103e0 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 vior in some fut
103f0 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 ure release of S
10400 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 QLite..**.** The
10410 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
10420 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 () routine does
10430 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d operating-system
10440 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 specific.** ini
10450 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 tialization of t
10460 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
10470 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f y. The sqlite3_
10480 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 os_end().** rout
10490 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 ine undoes the e
104a0 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 ffect of sqlite3
104b0 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 _os_init(). Typ
104c0 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 ical tasks.** pe
104d0 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 rformed by these
104e0 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 routines includ
104f0 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 e allocation or
10500 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 deallocation.**
10510 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 of static resour
10520 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 ces, initializat
10530 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 ion of global va
10540 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 riables,.** sett
10550 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 ing up a default
10560 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d [sqlite3_vfs] m
10570 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e odule, or settin
10580 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c g up.** a defaul
10590 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 t configuration
105a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
105b0 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 onfig()]..**.**
105c0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
105d0 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 should never inv
105e0 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 oke either sqlit
105f0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 e3_os_init().**
10600 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e or sqlite3_os_en
10610 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 d() directly. T
10620 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
10630 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b hould only invok
10640 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 e.** sqlite3_ini
10650 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 tialize() and sq
10660 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
10670 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f . The sqlite3_o
10680 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 s_init().** inte
10690 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 rface is called
106a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 automatically by
106b0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
106c0 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c ize() and.** sql
106d0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 ite3_os_end() is
106e0 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 called by sqlit
106f0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 e3_shutdown().
10700 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 Appropriate.** i
10710 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 mplementations f
10720 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e or sqlite3_os_in
10730 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 it() and sqlite3
10740 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 _os_end().** are
10750 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 built into SQLi
10760 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f te when it is co
10770 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c mpiled for Unix,
10780 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f Windows, or OS/
10790 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 2..** When [cust
107a0 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c om builds | buil
107b0 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 t for other plat
107c0 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 forms].** (using
107d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f the [SQLITE_OS_
107e0 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 OTHER=1] compile
107f0 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 -time.** option)
10800 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
10810 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 must supply a s
10820 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e uitable implemen
10830 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 tation for.** sq
10840 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
10850 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 and sqlite3_os_e
10860 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 nd(). An applic
10870 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a ation-supplied.*
10880 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
10890 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 of sqlite3_os_i
108a0 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 nit() or sqlite3
108b0 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 _os_end().** mus
108c0 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 t return [SQLITE
108d0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 _OK] on success
108e0 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b and some other [
108f0 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e error code] upon
10900 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a .** failure..*/.
10910 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
10920 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 QLITE_APICALL sq
10930 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
10940 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 (void);.SQLITE_A
10950 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 PI int SQLITE_AP
10960 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 68 ICALL sqlite3_sh
10970 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 utdown(void);.SQ
10980 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
10990 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 ITE_APICALL sqli
109a0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 te3_os_init(void
109b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
109c0 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c t SQLITE_APICALL
109d0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
109e0 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 void);../*.** CA
109f0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
10a00 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c ing The SQLite L
10a10 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 ibrary.**.** The
10a20 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
10a30 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 ) interface is u
10a40 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 sed to make glob
10a50 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e al configuration
10a60 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 .** changes to S
10a70 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 QLite in order t
10a80 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f o tune SQLite to
10a90 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 the specific ne
10aa0 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 eds of.** the ap
10ab0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 plication. The
10ac0 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
10ad0 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 ation is recomme
10ae0 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a nded for most.**
10af0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e applications an
10b00 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e d so this routin
10b10 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 e is usually not
10b20 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 necessary. It
10b30 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 is.** provided t
10b40 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 o support rare a
10b50 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 pplications with
10b60 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a unusual needs..
10b70 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c **.** <b>The sql
10b80 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
10b90 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 terface is not t
10ba0 68 72 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 hreadsafe. The a
10bb0 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 pplication.** mu
10bc0 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e st ensure that n
10bd0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 o other SQLite i
10be0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e nterfaces are in
10bf0 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a voked by other.*
10c00 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 * threads while
10c10 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
10c20 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e is running.</b>
10c30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
10c40 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 e3_config() inte
10c50 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c rface.** may onl
10c60 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 y be invoked pri
10c70 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e or to library in
10c80 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 itialization usi
10c90 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 ng.** [sqlite3_i
10ca0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 nitialize()] or
10cb0 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 after shutdown b
10cc0 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 y [sqlite3_shutd
10cd0 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 own()]..** ^If s
10ce0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
10cf0 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 is called after
10d00 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
10d10 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 ize()] and befor
10d20 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 e.** [sqlite3_sh
10d30 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 utdown()] then i
10d40 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 t will return SQ
10d50 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 LITE_MISUSE..**
10d60 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 Note, however, t
10d70 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e hat ^sqlite3_con
10d80 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c fig() can be cal
10d90 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 led as part of t
10da0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 he.** implementa
10db0 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 tion of an appli
10dc0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b cation-defined [
10dd0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
10de0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 )]..**.** The fi
10df0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
10e00 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
10e10 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a is an integer.*
10e20 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e * [configuration
10e30 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 option] that de
10e40 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 termines.** what
10e50 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c property of SQL
10e60 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e ite is to be con
10e70 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 figured. Subseq
10e80 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a uent arguments.*
10e90 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 * vary depending
10ea0 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 on the [configu
10eb0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a ration option].*
10ec0 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 * in the first a
10ed0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e rgument..**.** ^
10ee0 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 When a configura
10ef0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 tion option is s
10f00 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 et, sqlite3_conf
10f10 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 ig() returns [SQ
10f20 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 LITE_OK]..** ^If
10f30 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 the option is u
10f40 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 nknown or SQLite
10f50 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 is unable to se
10f60 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 t the option.**
10f70 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e then this routin
10f80 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d e returns a non-
10f90 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
10fa0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
10fb0 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 int SQLITE_CDEC
10fc0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 L sqlite3_config
10fd0 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a (int, ...);../*.
10fe0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
10ff0 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 figure database
11000 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d connections.** M
11010 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
11020 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
11030 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 _db_config() int
11040 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
11050 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 o make configura
11060 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
11070 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 to a [database c
11080 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 onnection]. The
11090 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 interface is si
110a0 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c milar to.** [sql
110b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 ite3_config()] e
110c0 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 xcept that the c
110d0 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 hanges apply to
110e0 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 a single.** [dat
110f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
11100 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 ] (specified in
11110 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
11120 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 nt)..**.** The s
11130 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
11140 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
11150 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 fig(D,V,...) is
11160 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
11170 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
11180 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 DE | configurati
11190 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e on verb] - an in
111a0 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 teger code .** t
111b0 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 hat indicates wh
111c0 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 at aspect of the
111d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
111e0 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 ction] is being
111f0 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 configured..** S
11200 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 ubsequent argume
11210 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 nts vary dependi
11220 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 ng on the config
11230 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a uration verb..**
11240 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 .** ^Calls to sq
11250 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
11260 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f ) return SQLITE_
11270 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 OK if and only i
11280 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 f.** the call is
11290 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 considered succ
112a0 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 essful..*/.SQLIT
112b0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
112c0 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 64 _CDECL sqlite3_d
112d0 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 b_config(sqlite3
112e0 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b *, int op, ...);
112f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
11300 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
11310 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a ion Routines.**.
11320 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
11330 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 f this object de
11340 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 fines the interf
11350 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 ace between SQLi
11360 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 te.** and low-le
11370 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 vel memory alloc
11380 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a ation routines..
11390 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 **.** This objec
113a0 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c t is used in onl
113b0 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 y one place in t
113c0 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 he SQLite interf
113d0 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 ace..** A pointe
113e0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
113f0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
11400 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 is the argument
11410 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
11420 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 onfig()] when th
11430 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
11440 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 option is.** [SQ
11450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
11460 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 OC] or [SQLITE_C
11470 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d ONFIG_GETMALLOC]
11480 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 . .** By creati
11490 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f ng an instance o
114a0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a f this object.**
114b0 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 and passing it
114c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to [sqlite3_conf
114d0 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ig]([SQLITE_CONF
114e0 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 IG_MALLOC]).** d
114f0 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 uring configurat
11500 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 ion, an applicat
11510 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 ion can specify
11520 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a an alternative.*
11530 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
11540 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f ion subsystem fo
11550 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 r SQLite to use
11560 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a for all of its.*
11570 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 * dynamic memory
11580 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f needs..**.** No
11590 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 te that SQLite c
115a0 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 omes with severa
115b0 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f l [built-in memo
115c0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a ry allocators].*
115d0 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 * that are perfe
115e0 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f ctly adequate fo
115f0 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 r the overwhelmi
11600 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 ng majority of a
11610 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 pplications.** a
11620 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a nd that this obj
11630 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 ect is only usef
11640 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e ul to a tiny min
11650 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 ority of applica
11660 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 tions.** with sp
11670 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 ecialized memory
11680 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 allocation requ
11690 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 irements. This
116a0 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 object is.** als
116b0 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 o used during te
116c0 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 sting of SQLite
116d0 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 in order to spec
116e0 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 ify an alternati
116f0 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c ve.** memory all
11700 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 ocator that simu
11710 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 lates memory out
11720 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 -of-memory condi
11730 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 tions in.** orde
11740 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 r to verify that
11750 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 SQLite recovers
11760 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d gracefully from
11770 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 such.** conditi
11780 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ons..**.** The x
11790 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 Malloc, xRealloc
117a0 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 , and xFree meth
117b0 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 ods must work li
117c0 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 ke the.** malloc
117d0 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e (), realloc() an
117e0 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f d free() functio
117f0 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ns from the stan
11800 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
11810 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 ** ^SQLite guara
11820 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 ntees that the s
11830 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
11840 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 o.** xRealloc is
11850 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 always a value
11860 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 returned by a pr
11870 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 ior call to xRou
11880 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a ndup..**.** xSiz
11890 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 e should return
118a0 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 the allocated si
118b0 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 ze of a memory a
118c0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 llocation.** pre
118d0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 viously obtained
118e0 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 from xMalloc or
118f0 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 xRealloc. The
11900 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a allocated size.*
11910 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c * is always at l
11920 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 east as big as t
11930 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a he requested siz
11940 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 e but may be lar
11950 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ger..**.** The x
11960 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 Roundup method r
11970 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c eturns what woul
11980 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 d be the allocat
11990 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 ed size of.** a
119a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
119b0 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 n given a partic
119c0 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 ular requested s
119d0 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 ize. Most memor
119e0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 y.** allocators
119f0 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 round up memory
11a00 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c allocations at l
11a10 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 east to the next
11a20 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 multiple.** of
11a30 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 8. Some allocat
11a40 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 ors round up to
11a50 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c a larger multipl
11a60 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 e or to a power
11a70 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d of 2..** Every m
11a80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
11a90 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 request coming
11aa0 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 in through [sqli
11ab0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a te3_malloc()].**
11ac0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
11ad0 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 lloc()] first ca
11ae0 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 lls xRoundup. I
11af0 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 f xRoundup retur
11b00 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 ns 0, .** that c
11b10 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 auses the corres
11b20 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 ponding memory a
11b30 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 llocation to fai
11b40 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e l..**.** The xIn
11b50 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 it method initia
11b60 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 lizes the memory
11b70 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 allocator. For
11b80 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 example,.** it
11b90 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 might allocate a
11ba0 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 ny require mutex
11bb0 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 es or initialize
11bc0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a internal data.*
11bd0 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 * structures. T
11be0 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 he xShutdown met
11bf0 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 hod is invoked (
11c00 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a indirectly) by.*
11c10 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 * [sqlite3_shutd
11c20 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c own()] and shoul
11c30 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 d deallocate any
11c40 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 resources acqui
11c50 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e red.** by xInit.
11c60 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 The pAppData p
11c70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 ointer is used a
11c80 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d s the only param
11c90 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 eter to.** xInit
11ca0 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a and xShutdown..
11cb0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c **.** SQLite hol
11cc0 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d ds the [SQLITE_M
11cd0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 UTEX_STATIC_MAST
11ce0 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 ER] mutex when i
11cf0 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 t invokes.** the
11d00 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 xInit method, s
11d10 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 o the xInit meth
11d20 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 od need not be t
11d30 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a hreadsafe. The.
11d40 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 ** xShutdown met
11d50 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c hod is only call
11d60 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
11d70 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 _shutdown()] so
11d80 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e it does.** not n
11d90 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 eed to be thread
11da0 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f safe either. Fo
11db0 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 r all other meth
11dc0 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 ods, SQLite.** h
11dd0 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 olds the [SQLITE
11de0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 _MUTEX_STATIC_ME
11df0 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 M] mutex as long
11e00 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 as the.** [SQLI
11e10 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
11e20 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 TUS] configurati
11e30 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 on option is tur
11e40 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a ned on (which.**
11e50 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c it is by defaul
11e60 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 t) and so the me
11e70 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 thods are automa
11e80 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a tically serializ
11e90 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 ed..** However,
11ea0 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 if [SQLITE_CONFI
11eb0 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 G_MEMSTATUS] is
11ec0 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 disabled, then t
11ed0 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 he other.** meth
11ee0 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 ods must be thre
11ef0 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d adsafe or else m
11f00 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 ake their own ar
11f10 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a rangements for.*
11f20 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e * serialization.
11f30 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 .**.** SQLite wi
11f40 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 ll never invoke
11f50 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 xInit() more tha
11f60 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 n once without a
11f70 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a n intervening.**
11f80 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f call to xShutdo
11f90 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 wn()..*/.typedef
11fa0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
11fb0 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 mem_methods sqli
11fc0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b te3_mem_methods;
11fd0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
11fe0 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 mem_methods {.
11ff0 76 6f 69 64 20 2a 28 53 51 4c 49 54 45 5f 43 41 void *(SQLITE_CA
12000 4c 4c 42 41 43 4b 20 2a 78 4d 61 6c 6c 6f 63 29 LLBACK *xMalloc)
12010 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f (int); /
12020 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * Memory allocat
12030 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a ion function */.
12040 20 20 76 6f 69 64 20 28 53 51 4c 49 54 45 5f 43 void (SQLITE_C
12050 41 4c 4c 42 41 43 4b 20 2a 78 46 72 65 65 29 28 ALLBACK *xFree)(
12060 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 void*);
12070 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 /* Free a prior
12080 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
12090 20 76 6f 69 64 20 2a 28 53 51 4c 49 54 45 5f 43 void *(SQLITE_C
120a0 41 4c 4c 42 41 43 4b 20 2a 78 52 65 61 6c 6c 6f ALLBACK *xReallo
120b0 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 c)(void*,int);
120c0 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c /* Resize an all
120d0 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 ocation */. int
120e0 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 (SQLITE_CALLBAC
120f0 4b 20 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 K *xSize)(void*)
12100 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 ; /* R
12110 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f eturn the size o
12120 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 f an allocation
12130 2a 2f 0a 20 20 69 6e 74 20 28 53 51 4c 49 54 45 */. int (SQLITE
12140 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 52 6f 75 6e _CALLBACK *xRoun
12150 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 dup)(int);
12160 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 /* Round up
12170 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 request size to
12180 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 allocation size
12190 2a 2f 0a 20 20 69 6e 74 20 28 53 51 4c 49 54 45 */. int (SQLITE
121a0 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 49 6e 69 74 _CALLBACK *xInit
121b0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
121c0 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a /* Initializ
121d0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
121e0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 ocator */. void
121f0 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 (SQLITE_CALLBAC
12200 4b 20 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f K *xShutdown)(vo
12210 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 id*); /* De
12220 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d initialize the m
12230 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
12240 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
12250 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 ata;
12260 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 /* Argument
12270 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 to xInit() and x
12280 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b Shutdown() */.};
12290 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
122a0 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 : Configuration
122b0 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f Options.** KEYWO
122c0 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 RDS: {configurat
122d0 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a ion option}.**.*
122e0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
122f0 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 s are the availa
12300 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 ble integer conf
12310 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
12320 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 s that.** can be
12330 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
12340 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
12350 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
12360 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
12370 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e e..**.** New con
12380 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
12390 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ns may be added
123a0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
123b0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
123c0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 Existing config
123d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
123e0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 might be discont
123f0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 inued. Applicat
12400 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 ions.** should c
12410 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
12420 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 code from [sqlit
12430 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 e3_config()] to
12440 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a make sure that.*
12450 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 * the call worke
12460 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 d. The [sqlite3
12470 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
12480 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e face will return
12490 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b a.** non-zero [
124a0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 error code] if a
124b0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 discontinued or
124c0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e unsupported con
124d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
124e0 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e n.** is invoked.
124f0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b .**.** <dl>.** [
12500 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
12510 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 INGLETHREAD]] <d
12520 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
12530 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 SINGLETHREAD</dt
12540 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
12550 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
12560 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
12570 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
12580 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
12590 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 ding mode] to Si
125a0 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e ngle-thread. In
125b0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 other words, it
125c0 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c disables.** all
125d0 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 mutexing and pu
125e0 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 ts SQLite into a
125f0 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 mode where it c
12600 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a an only be used.
12610 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 ** by a single t
12620 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c hread. ^If SQL
12630 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
12640 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
12650 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
12660 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
12670 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
12680 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
12690 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 * it is not poss
126a0 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 ible to change t
126b0 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f he [threading mo
126c0 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 de] from its def
126d0 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 ault.** value of
126e0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 Single-thread a
126f0 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 nd so [sqlite3_c
12700 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 onfig()] will re
12710 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 turn .** [SQLITE
12720 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 _ERROR] if calle
12730 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 d with the SQLIT
12740 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
12750 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 HREAD.** configu
12760 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
12770 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
12780 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
12790 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 HREAD]] <dt>SQLI
127a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
127b0 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 HREAD</dt>.** <d
127c0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 d>There are no a
127d0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
127e0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 option. ^This
127f0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a option sets the.
12800 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ** [threading mo
12810 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 de] to Multi-thr
12820 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 ead. In other w
12830 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 ords, it disable
12840 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e s.** mutexing on
12850 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
12860 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 ction] and [prep
12870 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
12880 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 objects..** The
12890 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 application is r
128a0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 esponsible for s
128b0 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 erializing acces
128c0 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 s to.** [databas
128d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 e connections] a
128e0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
128f0 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f tements]. But o
12900 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 ther mutexes.**
12910 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 are enabled so t
12920 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
12930 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 be safe to use i
12940 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 n a multi-thread
12950 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e ed.** environmen
12960 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 t as long as no
12970 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 two threads atte
12980 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 mpt to use the s
12990 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 ame.** [database
129a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 connection] at
129b0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 the same time.
129c0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
129d0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
129e0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
129f0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
12a00 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
12a10 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
12a20 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e then.** it is n
12a30 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 ot possible to s
12a40 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 et the Multi-thr
12a50 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d ead [threading m
12a60 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ode] and.** [sql
12a70 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
12a80 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
12a90 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c TE_ERROR] if cal
12aa0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
12ab0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
12ac0 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 LTITHREAD config
12ad0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c uration option.<
12ae0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
12af0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
12b00 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 LIZED]] <dt>SQLI
12b10 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
12b20 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 IZED</dt>.** <dd
12b30 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
12b40 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
12b50 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f option. ^This o
12b60 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
12b70 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 * [threading mod
12b80 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 e] to Serialized
12b90 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 . In other words
12ba0 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e , this option en
12bb0 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 ables.** all mut
12bc0 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 exes including t
12bd0 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 he recursive.**
12be0 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 mutexes on [data
12bf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
12c00 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
12c10 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 tatement] object
12c20 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f s..** In this mo
12c30 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 de (which is the
12c40 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 default when SQ
12c50 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
12c60 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 with.** [SQLITE
12c70 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 _THREADSAFE=1])
12c80 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
12c90 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 ry will itself s
12ca0 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a erialize access.
12cb0 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 ** to [database
12cc0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 connections] and
12cd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
12ce0 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 ments] so that t
12cf0 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f he.** applicatio
12d00 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 n is free to use
12d10 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
12d20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
12d30 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b or the.** same [
12d40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
12d50 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 nt] in different
12d60 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 threads at the
12d70 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 same time..** ^I
12d80 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
12d90 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
12da0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
12db0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
12dc0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
12dd0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
12de0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 hen.** it is not
12df0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 possible to set
12e00 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 the Serialized
12e10 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
12e20 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
12e30 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 _config()] will
12e40 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
12e50 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 RROR] if called
12e60 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 with the.** SQLI
12e70 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
12e80 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 IZED configurati
12e90 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a on option.</dd>.
12ea0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
12eb0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c ONFIG_MALLOC]] <
12ec0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
12ed0 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 _MALLOC</dt>.**
12ee0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 <dd> ^(The SQLIT
12ef0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 E_CONFIG_MALLOC
12f00 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
12f10 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
12f20 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f hich is .** a po
12f30 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
12f40 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
12f50 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
12f60 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 ] structure..**
12f70 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 The argument spe
12f80 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e cifies.** altern
12f90 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 ative low-level
12fa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
12fb0 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 n routines to be
12fc0 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f used in place o
12fd0 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 f.** the memory
12fe0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
12ff0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 nes built into S
13000 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 QLite.)^ ^SQLite
13010 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 makes.** its ow
13020 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f n private copy o
13030 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 f the content of
13040 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 the [sqlite3_me
13050 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 m_methods] struc
13060 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 ture.** before t
13070 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 he [sqlite3_conf
13080 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 ig()] call retur
13090 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ns.</dd>.**.** [
130a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
130b0 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 ETMALLOC]] <dt>S
130c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
130d0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
130e0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 dd> ^(The SQLITE
130f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
13100 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 C option takes a
13110 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
13120 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 which.** is a p
13130 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
13140 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 tance of the [sq
13150 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
13160 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a s] structure..**
13170 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 The [sqlite3_me
13180 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 m_methods].** st
13190 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 ructure is fille
131a0 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 d with the curre
131b0 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d ntly defined mem
131c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
131d0 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 outines.)^.** Th
131e0 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 is option can be
131f0 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 used to overloa
13200 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 d the default me
13210 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
13220 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 ** routines with
13230 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 a wrapper that
13240 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f simulations memo
13250 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
13260 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 ilure or.** trac
13270 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c ks memory usage,
13280 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f for example. </
13290 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
132a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
132b0 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 TUS]] <dt>SQLITE
132c0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
132d0 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e S</dt>.** <dd> ^
132e0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
132f0 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 G_MEMSTATUS opti
13300 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 on takes single
13310 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 argument of type
13320 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 int,.** interpr
13330 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 eted as a boolea
13340 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 n, which enables
13350 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 or disables the
13360 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a collection of.*
13370 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
13380 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 ion statistics.
13390 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c ^(When memory al
133a0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 location statist
133b0 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 ics are.** disab
133c0 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 led, the followi
133d0 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ng SQLite interf
133e0 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d aces become non-
133f0 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 operational:.**
13400 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e <ul>.** <li>
13410 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
13420 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c _used()].** <l
13430 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f i> [sqlite3_memo
13440 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a ry_highwater()].
13450 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
13460 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
13470 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 it64()].** <li
13480 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 > [sqlite3_statu
13490 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c s64()].** </ul
134a0 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 >)^.** ^Memory a
134b0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 llocation statis
134c0 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 tics are enabled
134d0 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 by default unle
134e0 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 ss SQLite is.**
134f0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 compiled with [S
13500 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 QLITE_DEFAULT_ME
13510 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 MSTATUS]=0 in wh
13520 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a ich case memory.
13530 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 ** allocation st
13540 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 atistics are dis
13550 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
13560 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
13570 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
13580 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 _SCRATCH]] <dt>S
13590 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
135a0 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATCH</dt>.** <dd
135b0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f > ^The SQLITE_CO
135c0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 NFIG_SCRATCH opt
135d0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
135e0 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
135f0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c ffer.** that SQL
13600 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 ite can use for
13610 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 scratch memory.
13620 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 ^(There are thr
13630 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 ee arguments.**
13640 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 to SQLITE_CONFIG
13650 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 _SCRATCH: A poi
13660 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a nter an 8-byte.*
13670 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 * aligned memory
13680 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 buffer from whi
13690 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 ch the scratch a
136a0 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 llocations will
136b0 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 be.** drawn, the
136c0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 size of each sc
136d0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e ratch allocation
136e0 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 (sz),.** and th
136f0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
13700 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f of scratch allo
13710 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a cations (N).)^.*
13720 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
13730 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 ment must be a p
13740 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 ointer to an 8-b
13750 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 yte aligned buff
13760 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 er.** of at leas
13770 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
13780 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 memory..** ^SQLi
13790 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 te will not use
137a0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 more than one sc
137b0 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 ratch buffers pe
137c0 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 r thread..** ^SQ
137d0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 Lite will never
137e0 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 request a scratc
137f0 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 h buffer that is
13800 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 more than 6.**
13810 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 times the databa
13820 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a se page size..**
13830 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 ^If SQLite need
13840 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e s needs addition
13850 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 al.** scratch me
13860 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 mory beyond what
13870 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 is provided by
13880 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 this configurati
13890 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 on option, then
138a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
138b0 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 loc()] will be u
138c0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 sed to obtain th
138d0 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e e memory needed.
138e0 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 <p>.** ^When the
138f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f application pro
13900 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 vides any amount
13910 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f of scratch memo
13920 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 ry using.** SQLI
13930 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
13940 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 H, SQLite avoids
13950 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 unnecessary lar
13960 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d ge.** [sqlite3_m
13970 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 alloc|heap alloc
13980 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 ations]..** This
13990 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f can help [Robso
139a0 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 n proof|prevent
139b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
139c0 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 n failures] due
139d0 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d to heap.** fragm
139e0 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d entation in low-
139f0 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 memory embedded
13a00 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 systems..** </dd
13a10 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
13a20 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
13a30 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 E]] <dt>SQLITE_C
13a40 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c ONFIG_PAGECACHE<
13a50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
13a60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
13a70 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e PAGECACHE option
13a80 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d specifies a mem
13a90 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 ory pool.** that
13aa0 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 SQLite can use
13ab0 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 for the database
13ac0 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 page cache with
13ad0 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 the default pag
13ae0 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 e.** cache imple
13af0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 mentation. .**
13b00 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 This configurati
13b10 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e on option is a n
13b20 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69 o-op if an appli
13b30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 cation-define pa
13b40 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c ge.** cache impl
13b50 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f ementation is lo
13b60 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b aded using the [
13b70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
13b80 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 ACHE2]..** ^Ther
13b90 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
13ba0 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f ments to SQLITE_
13bb0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
13bc0 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a : A pointer to.*
13bd0 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 * 8-byte aligned
13be0 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 memory (pMem),
13bf0 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 the size of each
13c00 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 page cache line
13c10 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 (sz),.** and th
13c20 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68 e number of cach
13c30 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 e lines (N)..**
13c40 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 The sz argument
13c50 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 should be the si
13c60 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 ze of the larges
13c70 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a t database page.
13c80 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 ** (a power of t
13c90 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 wo between 512 a
13ca0 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 nd 65536) plus s
13cb0 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20 ome extra bytes
13cc0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 for each.** page
13cd0 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e header. ^The n
13ce0 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 umber of extra b
13cf0 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 ytes needed by t
13d00 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a he page header.*
13d10 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 * can be determi
13d20 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 ned using [SQLIT
13d30 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f E_CONFIG_PCACHE_
13d40 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 HDRSZ]..** ^It i
13d50 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 s harmless, apar
13d60 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 t from the waste
13d70 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 d memory,.** for
13d80 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 the sz paramete
13d90 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 r to be larger t
13da0 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 han necessary.
13db0 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 The pMem.** argu
13dc0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74 ment must be eit
13dd0 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 her a NULL point
13de0 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 er or a pointer
13df0 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 to an 8-byte.**
13e00 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 aligned block of
13e10 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 memory of at le
13e20 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 ast sz*N bytes,
13e30 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 otherwise.** sub
13e40 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 sequent behavior
13e50 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
13e60 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 * ^When pMem is
13e70 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 not NULL, SQLite
13e80 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 will strive to
13e90 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 use the memory p
13ea0 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 rovided.** to sa
13eb0 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65 tisfy page cache
13ec0 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 needs, falling
13ed0 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 back to [sqlite3
13ee0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a _malloc()] if.**
13ef0 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 a page cache li
13f00 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 ne is larger tha
13f10 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66 n sz bytes or if
13f20 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d all of the pMem
13f30 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 buffer.** is ex
13f40 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 hausted..** ^If
13f50 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 pMem is NULL and
13f60 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 N is non-zero,
13f70 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61 then each databa
13f80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
13f90 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c does an initial
13fa0 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e bulk allocation
13fb0 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 for page cache
13fc0 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b memory.** from [
13fd0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
13fe0 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72 ] sufficient for
13ff0 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 N cache lines i
14000 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20 f N is positive
14010 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e or.** of -1024*N
14020 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e bytes if N is n
14030 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 egative, . ^If a
14040 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 dditional.** pag
14050 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 e cache memory i
14060 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 s needed beyond
14070 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 what is provided
14080 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a by the initial.
14090 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 ** allocation, t
140a0 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20 hen SQLite goes
140b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c to [sqlite3_mall
140c0 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79 oc()] separately
140d0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 for each.** add
140e0 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 itional cache li
140f0 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ne. </dd>.**.**
14100 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
14110 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 HEAP]] <dt>SQLIT
14120 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 E_CONFIG_HEAP</d
14130 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 t>.** <dd> ^The
14140 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
14150 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 AP option specif
14160 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d ies a static mem
14170 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 ory buffer .** t
14180 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
14190 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 use for all of i
141a0 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 ts dynamic memor
141b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
141c0 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f ds.** beyond tho
141d0 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 se provided for
141e0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 by [SQLITE_CONFI
141f0 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a G_SCRATCH] and.*
14200 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
14210 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 _PAGECACHE]..**
14220 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
14230 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 IG_HEAP option i
14240 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 s only available
14250 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
14260 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 mpiled.** with e
14270 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e ither [SQLITE_EN
14280 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 ABLE_MEMSYS3] or
14290 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
142a0 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 MEMSYS5] and ret
142b0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urns.** [SQLITE_
142c0 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 ERROR] if invoke
142d0 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 d otherwise..**
142e0 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 ^There are three
142f0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 arguments to SQ
14300 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
14310 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 :.** An 8-byte a
14320 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 ligned pointer t
14330 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a o the memory,.**
14340 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
14350 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f ytes in the memo
14360 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 ry buffer, and t
14370 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 he minimum alloc
14380 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e ation size..** ^
14390 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 If the first poi
143a0 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 nter (the memory
143b0 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c pointer) is NUL
143c0 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 L, then SQLite r
143d0 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 everts.** to usi
143e0 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d ng its default m
143f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
14400 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c (the system mall
14410 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 oc() implementat
14420 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 ion),.** undoing
14430 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 any prior invoc
14440 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 ation of [SQLITE
14450 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e _CONFIG_MALLOC].
14460 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d ^If the.** mem
14470 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e ory pointer is n
14480 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 ot NULL then the
14490 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d alternative mem
144a0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 ory.** allocator
144b0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 is engaged to h
144c0 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c andle all of SQL
144d0 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ites memory allo
144e0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a cation needs..**
144f0 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 The first point
14500 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 er (the memory p
14510 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 ointer) must be
14520 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d aligned to an 8-
14530 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 byte.** boundary
14540 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 or subsequent b
14550 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 ehavior of SQLit
14560 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 e will be undefi
14570 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 ned..** The mini
14580 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 mum allocation s
14590 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 ize is capped at
145a0 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 2**12. Reasonab
145b0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 le values.** for
145c0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
145d0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 ocation size are
145e0 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2**5 through 2*
145f0 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b *8.</dd>.**.** [
14600 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
14610 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 UTEX]] <dt>SQLIT
14620 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f E_CONFIG_MUTEX</
14630 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
14640 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
14650 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b MUTEX option tak
14660 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
14670 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a ment which is a.
14680 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e ** pointer to an
14690 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
146a0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
146b0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
146c0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d re..** The argum
146d0 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c ent specifies al
146e0 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 ternative low-le
146f0 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e vel mutex routin
14700 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a es to be used.**
14710 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 in place the mu
14720 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 tex routines bui
14730 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 lt into SQLite.)
14740 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 ^ ^SQLite makes
14750 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 a copy of.** th
14760 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
14770 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
14780 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
14790 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 re before the ca
147a0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
147b0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 3_config()] retu
147c0 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 rns. ^If SQLite
147d0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
147e0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
147f0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
14800 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
14810 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
14820 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 ption then.** th
14830 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e e entire mutexin
14840 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f g subsystem is o
14850 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 mitted from the
14860 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 build and hence
14870 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c calls to.** [sql
14880 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
14890 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 ith the SQLITE_C
148a0 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 ONFIG_MUTEX conf
148b0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
148c0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 will.** return
148d0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c [SQLITE_ERROR].<
148e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
148f0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
14900 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 TEX]] <dt>SQLITE
14910 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
14920 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
14930 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
14940 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f G_GETMUTEX optio
14950 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
14960 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a argument which.
14970 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ** is a pointer
14980 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
14990 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
149a0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 utex_methods] st
149b0 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a ructure. The.**
149c0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
149d0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 methods].** stru
149e0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 cture is filled
149f0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 with the current
14a00 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 ly defined mutex
14a10 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 routines.)^.**
14a20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 This option can
14a30 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c be used to overl
14a40 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 oad the default
14a50 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e mutex allocation
14a60 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 .** routines wit
14a70 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 h a wrapper used
14a80 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 to track mutex
14a90 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 usage for perfor
14aa0 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 mance.** profili
14ab0 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 ng or testing, f
14ac0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 or example. ^I
14ad0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
14ae0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
14af0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
14b00 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
14b10 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
14b20 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
14b30 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 hen.** the entir
14b40 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 e mutexing subsy
14b50 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 stem is omitted
14b60 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 from the build a
14b70 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 nd hence calls t
14b80 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
14b90 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 nfig()] with the
14ba0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
14bb0 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 ETMUTEX configur
14bc0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c ation option wil
14bd0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c l.** return [SQL
14be0 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e ITE_ERROR].</dd>
14bf0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
14c00 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
14c10 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
14c20 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
14c30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
14c40 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
14c50 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e LOOKASIDE option
14c60 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d takes two argum
14c70 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d ents that determ
14c80 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 ine.** the defau
14c90 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 lt size of looka
14ca0 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 side memory on e
14cb0 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f ach [database co
14cc0 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 nnection]..** Th
14cd0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
14ce0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 is the.** size
14cf0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 of each lookasid
14d00 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e e buffer slot an
14d10 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 d the second is
14d20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
14d30 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 slots allocated
14d40 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 to each databas
14d50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 e connection.)^
14d60 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ^(SQLITE_CONFIG
14d70 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 _LOOKASIDE.** se
14d80 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c ts the <i>defaul
14d90 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 t</i> lookaside
14da0 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 size. The [SQLIT
14db0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
14dc0 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 SIDE].** option
14dd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 to [sqlite3_db_c
14de0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 onfig()] can be
14df0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 used to change t
14e00 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 he lookaside.**
14e10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e configuration on
14e20 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e individual conn
14e30 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e ections.)^ </dd>
14e40 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
14e50 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d CONFIG_PCACHE2]]
14e60 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
14e70 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a IG_PCACHE2</dt>.
14e80 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
14e90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
14ea0 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 HE2 option takes
14eb0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
14ec0 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 nt which is .**
14ed0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
14ee0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
14ef0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 methods2] object
14f00 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 . This object s
14f10 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 pecifies.** the
14f20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 interface to a c
14f30 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 ustom page cache
14f40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
14f50 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 )^.** ^SQLite ma
14f60 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
14f70 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 e [sqlite3_pcach
14f80 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 e_methods2] obje
14f90 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ct.</dd>.**.** [
14fa0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
14fb0 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e ETPCACHE2]] <dt>
14fc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
14fd0 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a TPCACHE2</dt>.**
14fe0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 <dd> ^(The SQLI
14ff0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
15000 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 CHE2 option take
15010 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
15020 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ent which.** is
15030 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
15040 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
15050 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 methods2] object
15060 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 . SQLite copies
15070 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 of.** the curre
15080 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d nt page cache im
15090 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 plementation int
150a0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e o that object.)^
150b0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
150c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
150d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
150e0 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a NFIG_LOG</dt>.**
150f0 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 <dd> The SQLITE
15100 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 _CONFIG_LOG opti
15110 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f on is used to co
15120 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 nfigure the SQLi
15130 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 te.** global [er
15140 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 ror log]..** (^T
15150 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
15160 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 _LOG option take
15170 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a s two arguments:
15180 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a a pointer to a.
15190 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 ** function with
151a0 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 a call signatur
151b0 65 20 6f 66 20 76 6f 69 64 28 53 51 4c 49 54 45 e of void(SQLITE
151c0 5f 43 41 4c 4c 42 41 43 4b 20 2a 29 28 76 6f 69 _CALLBACK *)(voi
151d0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
151e0 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 r*), .** and a p
151f0 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 ointer to void.
15200 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e ^If the function
15210 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
15220 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 NULL, it is.** i
15230 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 nvoked by [sqlit
15240 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f e3_log()] to pro
15250 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e cess each loggin
15260 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 g event. ^If th
15270 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f e.** function po
15280 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 inter is NULL, t
15290 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 he [sqlite3_log(
152a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 )] interface bec
152b0 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a omes a no-op..**
152c0 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 ^The void point
152d0 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 er that is the s
152e0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
152f0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f o SQLITE_CONFIG_
15300 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 LOG is.** passed
15310 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 through as the
15320 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
15330 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 to the applicati
15340 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 on-defined logge
15350 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 r.** function wh
15360 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 enever that func
15370 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e tion is invoked.
15380 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 ^The second pa
15390 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 rameter to.** th
153a0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f e logger functio
153b0 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 n is a copy of t
153c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
153d0 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 er to the corres
153e0 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 ponding.** [sqli
153f0 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 te3_log()] call
15400 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 and is intended
15410 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 to be a [result
15420 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b code] or an.** [
15430 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
15440 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 code]. ^The thi
15450 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 rd parameter pas
15460 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 sed to the logge
15470 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 r is.** log mess
15480 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 age after format
15490 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 ting via [sqlite
154a0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 3_snprintf()]..*
154b0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 * The SQLite log
154c0 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 ging interface i
154d0 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b s not reentrant;
154e0 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 the logger func
154f0 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 tion.** supplied
15500 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
15510 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 ion must not inv
15520 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 oke any SQLite i
15530 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 nterface..** In
15540 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 a multi-threaded
15550 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 application, th
15560 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
15570 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 fined logger.**
15580 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 function must be
15590 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 threadsafe. </d
155a0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
155b0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c E_CONFIG_URI]] <
155c0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
155d0 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 _URI.** <dd>^(Th
155e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
155f0 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 URI option takes
15600 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
15610 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a nt of type int..
15620 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 ** If non-zero,
15630 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e then URI handlin
15640 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e g is globally en
15650 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 abled. If the pa
15660 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c rameter is zero,
15670 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e .** then URI han
15680 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c dling is globall
15690 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 y disabled.)^ ^I
156a0 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 f URI handling i
156b0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e s globally.** en
156c0 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e abled, all filen
156d0 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b ames passed to [
156e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
156f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
15700 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 2()],.** [sqlite
15710 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 3_open16()] or.*
15720 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 * specified as p
15730 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 art of [ATTACH]
15740 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 commands are int
15750 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 erpreted as URIs
15760 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 , regardless.**
15770 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
15780 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 t the [SQLITE_OP
15790 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 EN_URI] flag is
157a0 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 set when the dat
157b0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
157c0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e ion is opened. ^
157d0 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c If it is globall
157e0 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 y disabled, file
157f0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c names are.** onl
15800 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 y interpreted as
15810 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c URIs if the SQL
15820 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 ITE_OPEN_URI fla
15830 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 g is set when th
15840 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
15850 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e nnection is open
15860 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 ed. ^(By default
15870 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 , URI handling i
15880 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 s globally.** di
15890 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 sabled. The defa
158a0 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 ult value may be
158b0 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 changed by comp
158c0 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a iling with the.*
158d0 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 * [SQLITE_USE_UR
158e0 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 I] symbol define
158f0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d.)^.**.** [[SQL
15900 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
15910 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d ING_INDEX_SCAN]]
15920 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
15930 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 IG_COVERING_INDE
15940 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 X_SCAN.** <dd>^T
15950 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
15960 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f _COVERING_INDEX_
15970 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 SCAN option take
15980 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 s a single integ
15990 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 er.** argument w
159a0 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 hich is interpre
159b0 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e ted as a boolean
159c0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 in order to ena
159d0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a ble or disable.*
159e0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 * the use of cov
159f0 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f ering indices fo
15a00 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 r full table sca
15a10 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 ns in the query
15a20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 optimizer..** ^T
15a30 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 he default setti
15a40 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 ng is determined
15a50 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 .** by the [SQLI
15a60 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e TE_ALLOW_COVERIN
15a70 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f G_INDEX_SCAN] co
15a80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
15a90 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a n, or is "on".**
15aa0 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 if that compile
15ab0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 -time option is
15ac0 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 omitted..** The
15ad0 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 ability to disab
15ae0 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f le the use of co
15af0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 vering indices f
15b00 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 or full table sc
15b10 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 ans.** is becaus
15b20 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 e some incorrect
15b30 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 ly coded legacy
15b40 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 applications mig
15b50 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a ht malfunction.*
15b60 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d * when the optim
15b70 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c ization is enabl
15b80 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 ed. Providing t
15b90 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a he ability to.**
15ba0 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 disable the opt
15bb0 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 imization allows
15bc0 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 the older, bugg
15bd0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f y application co
15be0 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 de to work.** wi
15bf0 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 thout change eve
15c00 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 n with newer ver
15c10 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e sions of SQLite.
15c20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
15c30 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 CONFIG_PCACHE]]
15c40 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
15c50 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c GETPCACHE]].** <
15c60 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
15c70 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 _PCACHE and SQLI
15c80 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
15c90 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 CHE.** <dd> Thes
15ca0 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 e options are ob
15cb0 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c solete and shoul
15cc0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 d not be used by
15cd0 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 new code..** Th
15ce0 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 ey are retained
15cf0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f for backwards co
15d00 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 mpatibility but
15d10 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a are now no-ops..
15d20 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ** </dd>.**.** [
15d30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
15d40 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 QLLOG]].** <dt>S
15d50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c QLITE_CONFIG_SQL
15d60 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 LOG.** <dd>This
15d70 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 option is only a
15d80 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 vailable if sqli
15d90 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
15da0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
15db0 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 TE_ENABLE_SQLLOG
15dc0 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 ] pre-processor
15dd0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 macro defined. T
15de0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
15df0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 t should.** be a
15e00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 pointer to a fu
15e10 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 nction of type v
15e20 6f 69 64 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 oid(SQLITE_CALLB
15e30 41 43 4b 20 2a 29 28 76 6f 69 64 2a 2c 73 71 6c ACK *)(void*,sql
15e40 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 ite3*,const char
15e50 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 *, int)..** The
15e60 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 second should be
15e70 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 of type (void*)
15e80 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 . The callback i
15e90 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 s invoked by the
15ea0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 library.** in t
15eb0 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 hree separate ci
15ec0 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 rcumstances, ide
15ed0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 ntified by the v
15ee0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 alue passed as t
15ef0 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 he.** fourth par
15f00 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 ameter. If the f
15f10 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
15f20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 is 0, then the d
15f30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
15f40 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 on.** passed as
15f50 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
15f60 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 ent has just bee
15f70 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 n opened. The th
15f80 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ird argument.**
15f90 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 points to a buff
15fa0 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 er containing th
15fb0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 e name of the ma
15fc0 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 in database file
15fd0 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 . If the.** four
15fe0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
15ff0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 1, then the SQL
16000 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 statement that t
16010 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
16020 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 er.** points to
16030 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 has just been ex
16040 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 ecuted. Or, if t
16050 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
16060 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a ter is 2, then.*
16070 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e * the connection
16080 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 being passed as
16090 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
160a0 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 meter is being c
160b0 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 losed. The.** th
160c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
160d0 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 passed NULL In
160e0 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 this case. An e
160f0 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 xample of using
16100 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 this.** configur
16110 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e ation option can
16120 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 be seen in the
16130 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 "test_sqllog.c"
16140 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a source file in.*
16150 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 * the canonical
16160 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 SQLite source tr
16170 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ee.</dd>.**.** [
16180 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
16190 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 MAP_SIZE]].** <d
161a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
161b0 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 MMAP_SIZE.** <dd
161c0 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f >^SQLITE_CONFIG_
161d0 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 MMAP_SIZE takes
161e0 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 two 64-bit integ
161f0 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 er (sqlite3_int6
16200 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 4) values.** tha
16210 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c t are the defaul
16220 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 t mmap size limi
16230 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 t (the default s
16240 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 etting for.** [P
16250 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d RAGMA mmap_size]
16260 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 ) and the maximu
16270 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 m allowed mmap s
16280 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 ize limit..** ^T
16290 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 he default setti
162a0 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 ng can be overri
162b0 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 dden by each dat
162c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
162d0 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 using.** either
162e0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 the [PRAGMA mma
162f0 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c p_size] command,
16300 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 or by using the
16310 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 .** [SQLITE_FCNT
16320 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c L_MMAP_SIZE] fil
16330 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 e control. ^(Th
16340 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 e maximum allowe
16350 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 d mmap size.** w
16360 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 ill be silently
16370 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 truncated if nec
16380 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 essary so that i
16390 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 t does not excee
163a0 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 d the.** compile
163b0 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d -time maximum mm
163c0 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 ap size set by t
163d0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 he.** [SQLITE_MA
163e0 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d X_MMAP_SIZE] com
163f0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
16400 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 .)^.** ^If eithe
16410 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 r argument to th
16420 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 is option is neg
16430 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 ative, then that
16440 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 argument is.**
16450 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 changed to its c
16460 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 ompile-time defa
16470 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c ult..**.** [[SQL
16480 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 ITE_CONFIG_WIN32
16490 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c _HEAPSIZE]].** <
164a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
164b0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a _WIN32_HEAPSIZE.
164c0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 ** <dd>^The SQLI
164d0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f TE_CONFIG_WIN32_
164e0 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 HEAPSIZE option
164f0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c is only availabl
16500 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a e if SQLite is.*
16510 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 * compiled for W
16520 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 indows with the
16530 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 [SQLITE_WIN32_MA
16540 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 LLOC] pre-proces
16550 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 sor macro.** def
16560 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f ined. ^SQLITE_CO
16570 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 NFIG_WIN32_HEAPS
16580 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 IZE takes a 32-b
16590 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 it unsigned inte
165a0 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 ger value.** tha
165b0 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 t specifies the
165c0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 maximum size of
165d0 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70 the created heap
165e0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ..**.** [[SQLITE
165f0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 _CONFIG_PCACHE_H
16600 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 DRSZ]].** <dt>SQ
16610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
16620 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e HE_HDRSZ.** <dd>
16630 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
16640 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 IG_PCACHE_HDRSZ
16650 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
16660 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 ingle parameter
16670 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f which.** is a po
16680 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
16690 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 ger and writes i
166a0 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 nto that integer
166b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
166c0 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 xtra.** bytes pe
166d0 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20 r page required
166e0 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e for each page in
166f0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
16700 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 PAGECACHE]..** T
16710 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 he amount of ext
16720 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65 ra space require
16730 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 d can change dep
16740 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f ending on the co
16750 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 mpiler,.** targe
16760 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 t platform, and
16770 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a SQLite version..
16780 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
16790 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a ONFIG_PMASZ]].**
167a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
167b0 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e IG_PMASZ.** <dd>
167c0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
167d0 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 IG_PMASZ option
167e0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 takes a single p
167f0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a arameter which.*
16800 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 * is an unsigned
16810 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 integer and set
16820 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 s the "Minimum P
16830 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 MA Size" for the
16840 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a multithreaded.*
16850 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 * sorter to that
16860 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 integer. The d
16870 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 efault minimum P
16880 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 MA Size is set b
16890 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 y the.** [SQLITE
168a0 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 _SORTER_PMASZ] c
168b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
168c0 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 on. New threads
168d0 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a are launched.**
168e0 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f to help with so
168f0 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 rt operations wh
16900 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 en multithreaded
16910 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 sorting.** is e
16920 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 nabled (using th
16930 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 e [PRAGMA thread
16940 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 s] command) and
16950 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f the amount of co
16960 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 ntent.** to be s
16970 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68 orted exceeds th
16980 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 e page size time
16990 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 s the minimum of
169a0 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 the.** [PRAGMA
169b0 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 cache_size] sett
169c0 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c ing and this val
169d0 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 ue..**.** [[SQLI
169e0 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 TE_CONFIG_STMTJR
169f0 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 NL_SPILL]].** <d
16a00 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
16a10 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a STMTJRNL_SPILL.*
16a20 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 * <dd>^The SQLIT
16a30 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e E_CONFIG_STMTJRN
16a40 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 L_SPILL option t
16a50 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 akes a single pa
16a60 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a rameter which.**
16a70 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 becomes the [st
16a80 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d atement journal]
16a90 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 spill-to-disk t
16aa0 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b hreshold. .** [
16ab0 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 Statement journa
16ac0 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e 20 ls] are held in
16ad0 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 memory until the
16ae0 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74 65 ir size (in byte
16af0 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74 68 s).** exceeds th
16b00 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 is threshold, at
16b10 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68 65 which point the
16b20 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f y are written to
16b30 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 disk..** Or if
16b40 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69 73 the threshold is
16b50 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a -1, statement j
16b60 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 ournals are alwa
16b70 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 ys held.** exclu
16b80 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 sively in memory
16b90 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 ..** Since many
16ba0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 statement journa
16bb0 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 ls never become
16bc0 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20 74 large, setting t
16bd0 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 he spill.** thre
16be0 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 shold to a value
16bf0 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20 63 such as 64KiB c
16c00 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75 63 an greatly reduc
16c10 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a e the amount of.
16c20 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64 20 ** I/O required
16c30 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74 65 to support state
16c40 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a ment rollback..*
16c50 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 * The default va
16c60 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65 74 lue for this set
16c70 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c ting is controll
16c80 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 ed by the.** [SQ
16c90 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 LITE_STMTJRNL_SP
16ca0 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ILL] compile-tim
16cb0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 e option..** </d
16cc0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
16cd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
16ce0 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 LETHREAD 1 /*
16cf0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nil */.#define S
16d00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
16d10 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a TITHREAD 2 /*
16d20 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nil */.#define
16d30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
16d40 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f RIALIZED 3 /
16d50 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
16d60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
16d70 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 ALLOC 4
16d80 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d /* sqlite3_mem_m
16d90 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
16da0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16db0 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 _GETMALLOC 5
16dc0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d /* sqlite3_mem
16dd0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
16de0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16df0 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 IG_SCRATCH
16e00 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 6 /* void*, in
16e10 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 t sz, int N */.#
16e20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
16e30 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 NFIG_PAGECACHE
16e40 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 7 /* void*,
16e50 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f int sz, int N */
16e60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16e70 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 CONFIG_HEAP
16e80 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 8 /* void*
16e90 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 , int nByte, int
16ea0 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 min */.#define
16eb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
16ec0 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f MSTATUS 9 /
16ed0 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 * boolean */.#de
16ee0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16ef0 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 IG_MUTEX
16f00 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 10 /* sqlite3_m
16f10 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f utex_methods* */
16f20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16f30 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 CONFIG_GETMUTEX
16f40 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 11 /* sqlit
16f50 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
16f60 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 * */./* previous
16f70 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ly SQLITE_CONFIG
16f80 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 _CHUNKALLOC 12 w
16f90 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 hich is now unus
16fa0 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 ed. */ .#define
16fb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
16fc0 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f OKASIDE 13 /
16fd0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 * int int */.#de
16fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16ff0 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 IG_PCACHE
17000 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 14 /* no-op */.
17010 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
17020 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 ONFIG_GETPCACHE
17030 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 15 /* no-op
17040 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17050 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 E_CONFIG_LOG
17060 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 16 /* xFu
17070 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 nc, void* */.#de
17080 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
17090 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 IG_URI
170a0 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 17 /* int */.#d
170b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
170c0 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 FIG_PCACHE2
170d0 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 18 /* sqlite3_
170e0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a pcache_methods2*
170f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17100 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
17110 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 CHE2 19 /* sq
17120 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
17130 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e hods2* */.#defin
17140 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
17150 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 COVERING_INDEX_S
17160 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a CAN 20 /* int *
17170 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17180 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 _CONFIG_SQLLOG
17190 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 21 /* xSql
171a0 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 log, void* */.#d
171b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
171c0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 FIG_MMAP_SIZE
171d0 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 22 /* sqlite3_
171e0 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 int64, sqlite3_i
171f0 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nt64 */.#define
17200 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 SQLITE_CONFIG_WI
17210 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 N32_HEAPSIZE
17220 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 23 /* int nBy
17230 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 te */.#define SQ
17240 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
17250 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 HE_HDRSZ
17260 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 24 /* int *psz
17270 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17280 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 E_CONFIG_PMASZ
17290 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 25
172a0 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 /* unsigned int
172b0 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e szPma */.#defin
172c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
172d0 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 STMTJRNL_SPILL
172e0 20 20 20 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 26 /* int n
172f0 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 Byte */../*.** C
17300 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
17310 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e e Connection Con
17320 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f figuration Optio
17330 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 ns.**.** These c
17340 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 onstants are the
17350 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 available integ
17360 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e er configuration
17370 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a options that.**
17380 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 can be passed a
17390 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
173a0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 ument to the [sq
173b0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
173c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
173d0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 .** New configur
173e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 ation options ma
173f0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
17400 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
17410 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 SQLite..** Exis
17420 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 ting configurati
17430 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 on options might
17440 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 be discontinued
17450 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a . Applications.
17460 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 ** should check
17470 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 the return code
17480 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 from [sqlite3_db
17490 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 _config()] to ma
174a0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 ke sure that.**
174b0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e the call worked.
174c0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ^The [sqlite3_
174d0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 db_config()] int
174e0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
174f0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
17500 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
17510 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
17520 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
17530 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
17540 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
17550 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
17560 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
17570 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
17580 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
17590 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 s option takes t
175a0 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 hree additional
175b0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 arguments that d
175c0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a etermine the .**
175d0 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f [lookaside memo
175e0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f ry allocator] co
175f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 nfiguration for
17600 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
17610 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 nnection]..** ^T
17620 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
17630 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 t (the third par
17640 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
17650 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
17660 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 is a.** pointer
17670 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 to a memory buff
17680 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f er to use for lo
17690 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a okaside memory..
176a0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
176b0 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 gument after the
176c0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
176d0 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a _LOOKASIDE verb.
176e0 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 ** may be NULL i
176f0 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c n which case SQL
17700 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 ite will allocat
17710 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 e the.** lookasi
17720 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 de buffer itself
17730 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
17740 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 malloc()]. ^The
17750 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
17760 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f is the.** size o
17770 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 f each lookaside
17780 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e buffer slot. ^
17790 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
177a0 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 nt is the number
177b0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 of.** slots. T
177c0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 he size of the b
177d0 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 uffer in the fir
177e0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 st argument must
177f0 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e be greater than
17800 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 .** or equal to
17810 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 the product of t
17820 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
17830 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 ird arguments.
17840 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 The buffer.** mu
17850 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f st be aligned to
17860 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 an 8-byte bound
17870 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 ary. ^If the se
17880 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
17890 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e .** SQLITE_DBCON
178a0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 FIG_LOOKASIDE is
178b0 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 not a multiple
178c0 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 of 8, it is inte
178d0 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 rnally.** rounde
178e0 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 d down to the ne
178f0 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 xt smaller multi
17900 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 ple of 8. ^(The
17910 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
17920 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 y.** configurati
17930 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 on for a databas
17940 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e e connection can
17950 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 only be changed
17960 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f when that.** co
17970 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 nnection is not
17980 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 currently using
17990 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
179a0 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f , or in other wo
179b0 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 rds.** when the
179c0 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 "current value"
179d0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
179e0 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 sqlite3_db_statu
179f0 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e s](D,[SQLITE_CON
17a00 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e FIG_LOOKASIDE],.
17a10 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 ..) is zero..**
17a20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 Any attempt to c
17a30 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 hange the lookas
17a40 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 ide memory confi
17a50 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f guration when lo
17a60 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 okaside.** memor
17a70 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 y is in use leav
17a80 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 es the configura
17a90 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 tion unchanged a
17aa0 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b nd returns .** [
17ab0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c SQLITE_BUSY].)^<
17ac0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
17ad0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
17ae0 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a NABLE_FKEY</dt>.
17af0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
17b00 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
17b10 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
17b20 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e e the enforcemen
17b30 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e t of.** [foreign
17b40 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 key constraints
17b50 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 ]. There should
17b60 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
17b70 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
17b80 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
17b90 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
17ba0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 r which is 0 to
17bb0 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 disable FK enfor
17bc0 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 cement,.** posit
17bd0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b ive to enable FK
17be0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 enforcement or
17bf0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 negative to leav
17c00 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 e FK enforcement
17c10 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 .** unchanged.
17c20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
17c30 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
17c40 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
17c50 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 into which.** is
17c60 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
17c70 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
17c80 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 her FK enforceme
17c90 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a nt is off or on.
17ca0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 ** following thi
17cb0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 s call. The sec
17cc0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 ond parameter ma
17cd0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e y be a NULL poin
17ce0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 ter, in.** which
17cf0 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 case the FK enf
17d00 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 orcement setting
17d10 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 is not reported
17d20 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a back. </dd>.**.
17d30 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ** <dt>SQLITE_DB
17d40 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 CONFIG_ENABLE_TR
17d50 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 IGGER</dt>.** <d
17d60 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
17d70 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c is used to enabl
17d80 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 e or disable [CR
17d90 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 EATE TRIGGER | t
17da0 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 riggers]..** The
17db0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f re should be two
17dc0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
17dd0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 ments..** The fi
17de0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
17df0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 an integer which
17e00 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 is 0 to disable
17e10 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f triggers,.** po
17e20 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 sitive to enable
17e30 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 triggers or neg
17e40 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 ative to leave t
17e50 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 he setting uncha
17e60 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 nged..** The sec
17e70 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
17e80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
17e90 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 integer into wh
17ea0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 ich.** is writte
17eb0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 n 0 or 1 to indi
17ec0 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 cate whether tri
17ed0 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c ggers are disabl
17ee0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a ed or enabled.**
17ef0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 following this
17f00 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e call. The secon
17f10 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 d parameter may
17f20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 be a NULL pointe
17f30 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 r, in.** which c
17f40 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 ase the trigger
17f50 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 setting is not r
17f60 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f eported back. </
17f70 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
17f80 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
17f90 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 ABLE_FTS3_TOKENI
17fa0 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ZER</dt>.** <dd>
17fb0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 ^This option is
17fc0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 used to enable
17fd0 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 74 or disable the t
17fe0 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 wo-argument.** v
17ff0 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 ersion of the [f
18000 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d ts3_tokenizer()]
18010 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 function which
18020 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a is part of the.*
18030 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 * [FTS3] full-te
18040 78 74 20 73 65 61 72 63 68 20 65 6e 67 69 6e 65 xt search engine
18050 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 extension..** T
18060 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 here should be t
18070 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 wo additional ar
18080 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 guments..** The
18090 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
180a0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 s an integer whi
180b0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 ch is 0 to disab
180c0 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 le fts3_tokenize
180d0 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 r() or.** positi
180e0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 ve to enable fts
180f0 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 3_tokenizer() or
18100 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 negative to lea
18110 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a ve the setting.*
18120 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 * unchanged..**
18130 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
18140 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
18150 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
18160 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 into which.** is
18170 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
18180 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
18190 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a her fts3_tokeniz
181a0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f er is disabled o
181b0 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c r enabled.** fol
181c0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c lowing this call
181d0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
181e0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 rameter may be a
181f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 NULL pointer, i
18200 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 n.** which case
18210 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 the new setting
18220 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 is not reported
18230 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a back. </dd>.**.*
18240 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
18250 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 ONFIG_ENABLE_LOA
18260 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e D_EXTENSION</dt>
18270 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
18280 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f ption is used to
18290 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 enable or disab
182a0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f le the [sqlite3_
182b0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
182c0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 ].** interface i
182d0 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 ndependently of
182e0 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 the [load_extens
182f0 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 ion()] SQL funct
18300 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c ion..** The [sql
18310 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 ite3_enable_load
18320 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 _extension()] AP
18330 49 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 I enables or dis
18340 61 62 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a ables both the.*
18350 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 * C-API [sqlite3
18360 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
18370 29 5d 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 )] and the SQL f
18380 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 unction [load_ex
18390 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 tension()]..** T
183a0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 here should be t
183b0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 wo additional ar
183c0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e guments..** When
183d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
183e0 65 6e 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 ent to this inte
183f0 72 66 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e rface is 1, then
18400 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 only the C-API
18410 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e is.** enabled an
18420 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 d the SQL functi
18430 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 on remains disab
18440 6c 65 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 led. If the fir
18450 73 74 20 61 72 67 6d 65 6e 74 20 74 6f 0a 2a 2a st argment to.**
18460 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
18470 69 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 is 0, then both
18480 74 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 the C-API and th
18490 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 e SQL function a
184a0 72 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 re disabled..**
184b0 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67 If the first arg
184c0 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 ument is -1, the
184d0 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 n no changes are
184e0 20 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f made to state o
184f0 66 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 f either the.**
18500 43 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c C-API or the SQL
18510 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 function..** Th
18520 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
18530 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
18540 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e to an integer in
18550 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 to which.** is w
18560 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f ritten 0 or 1 to
18570 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 indicate whethe
18580 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f r [sqlite3_load_
18590 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 extension()] int
185a0 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 erface.** is dis
185b0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 abled or enabled
185c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 following this
185d0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e call. The secon
185e0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a d parameter may.
185f0 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 ** be a NULL poi
18600 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 nter, in which c
18610 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 ase the new sett
18620 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 ing is not repor
18630 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 ted back..** </d
18640 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a d>.**.** </dl>.*
18650 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18660 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
18670 49 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20 IDE
18680 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 1001 /* void* in
18690 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 t int */.#define
186a0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
186b0 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 _ENABLE_FKEY
186c0 20 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 1002 /* i
186d0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 nt int* */.#defi
186e0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
186f0 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 IG_ENABLE_TRIGGE
18700 52 20 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a R 1003 /*
18710 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 int int* */.#de
18720 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
18730 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 NFIG_ENABLE_FTS3
18740 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 _TOKENIZER 1004
18750 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 /* int int* */.#
18760 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
18770 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f CONFIG_ENABLE_LO
18780 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 AD_EXTENSION 100
18790 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 5 /* int int* */
187a0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
187b0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 F: Enable Or Dis
187c0 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 able Extended Re
187d0 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 sult Codes.** ME
187e0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
187f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
18800 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
18810 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 _codes() routine
18820 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
18830 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 bles the.** [ext
18840 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
18850 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 es] feature of S
18860 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 QLite. ^The exte
18870 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 nded result.** c
18880 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 odes are disable
18890 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 d by default for
188a0 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 historical comp
188b0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 atibility..*/.SQ
188c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
188d0 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 ITE_APICALL sqli
188e0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 te3_extended_res
188f0 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 ult_codes(sqlite
18900 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 3*, int onoff);.
18910 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
18920 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 Last Insert Row
18930 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 id.** METHOD: sq
18940 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 lite3.**.** ^Eac
18950 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 h entry in most
18960 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 SQLite tables (e
18970 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f xcept for [WITHO
18980 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 UT ROWID] tables
18990 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 ).** has a uniqu
189a0 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a e 64-bit signed.
189b0 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 ** integer key c
189c0 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 alled the [ROWID
189d0 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 | "rowid"]. ^Th
189e0 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 e rowid is alway
189f0 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 s available.** a
18a00 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 s an undeclared
18a10 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 column named ROW
18a20 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 ID, OID, or _ROW
18a30 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 ID_ as long as t
18a40 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 hose.** names ar
18a50 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 e not also used
18a60 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 by explicitly de
18a70 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 clared columns.
18a80 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 ^If.** the table
18a90 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 has a column of
18aa0 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 type [INTEGER P
18ab0 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e RIMARY KEY] then
18ac0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 that column.**
18ad0 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 is another alias
18ae0 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a for the rowid..
18af0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
18b00 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
18b10 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 owid(D) interfac
18b20 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 e returns the [r
18b30 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a owid] of the .**
18b40 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 most recent suc
18b50 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
18b60 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 into a rowid ta
18b70 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 ble or [virtual
18b80 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 table].** on dat
18b90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18ba0 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 D..** ^Inserts
18bb0 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f into [WITHOUT RO
18bc0 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 WID] tables are
18bd0 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a not recorded..**
18be0 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 ^If no successf
18bf0 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 ul [INSERT]s int
18c00 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a o rowid tables.*
18c10 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 * have ever occu
18c20 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 rred on the data
18c30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
18c40 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 D, .** then sqli
18c50 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
18c60 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 rowid(D) returns
18c70 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 zero..**.** ^(I
18c80 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 f an [INSERT] oc
18c90 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 curs within a tr
18ca0 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 igger or within
18cb0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 a [virtual table
18cc0 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 ].** method, the
18cd0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 n this routine w
18ce0 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b ill return the [
18cf0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e rowid] of the in
18d00 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 serted.** row as
18d10 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 long as the tri
18d20 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 gger or virtual
18d30 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 table method is
18d40 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 running..** But
18d50 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 once the trigger
18d60 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c or virtual tabl
18d70 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 e method ends, t
18d80 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
18d90 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f d .** by this ro
18da0 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f utine reverts to
18db0 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 what it was bef
18dc0 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 ore the trigger
18dd0 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 or virtual.** ta
18de0 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e ble method began
18df0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 .)^.**.** ^An [I
18e00 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c NSERT] that fail
18e10 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 s due to a const
18e20 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 raint violation
18e30 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 is not a.** succ
18e40 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 essful [INSERT]
18e50 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 and does not cha
18e60 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 nge the value re
18e70 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a turned by this.*
18e80 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 * routine. ^Thu
18e90 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c s INSERT OR FAIL
18ea0 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f , INSERT OR IGNO
18eb0 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f RE, INSERT OR RO
18ec0 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 LLBACK,.** and I
18ed0 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d NSERT OR ABORT m
18ee0 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 ake no changes t
18ef0 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c o the return val
18f00 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f ue of this.** ro
18f10 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 utine when their
18f20 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 insertion fails
18f30 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 . ^(When INSERT
18f40 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 OR REPLACE.** e
18f50 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 ncounters a cons
18f60 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e traint violation
18f70 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 , it does not fa
18f80 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 il. The.** INSE
18f90 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 RT continues to
18fa0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 completion after
18fb0 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 deleting rows t
18fc0 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 hat caused.** th
18fd0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f e constraint pro
18fe0 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f blem so INSERT O
18ff0 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 R REPLACE will a
19000 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 lways change.**
19010 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
19020 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 of this interfa
19030 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 ce.)^.**.** ^For
19040 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 the purposes of
19050 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 this routine, a
19060 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f n [INSERT] is co
19070 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 nsidered to.** b
19080 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 e successful eve
19090 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 n if it is subse
190a0 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 quently rolled b
190b0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ack..**.** This
190c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 function is acce
190d0 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 ssible to SQL st
190e0 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 atements via the
190f0 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 .** [last_insert
19100 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e _rowid() SQL fun
19110 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 ction]..**.** If
19120 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
19130 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 ad performs a ne
19140 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 w [INSERT] on th
19150 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 e same.** databa
19160 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 se connection wh
19170 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ile the [sqlite3
19180 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
19190 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f id()].** functio
191a0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 n is running and
191b0 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 thus changes th
191c0 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 e last insert [r
191d0 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 owid],.** then t
191e0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
191f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 d by [sqlite3_la
19200 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
19210 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 )] is.** unpredi
19220 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 ctable and might
19230 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 not equal eithe
19240 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 r the old or the
19250 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 new.** last ins
19260 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a ert [rowid]..*/.
19270 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
19280 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f e3_int64 SQLITE_
19290 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f APICALL sqlite3_
192a0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
192b0 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a d(sqlite3*);../*
192c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
192d0 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f unt The Number O
192e0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a f Rows Modified.
192f0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
19300 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 e3.**.** ^This f
19310 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
19320 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f the number of ro
19330 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 ws modified, ins
19340 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 erted or.** dele
19350 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 ted by the most
19360 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 recently complet
19370 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 ed INSERT, UPDAT
19380 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 E or DELETE.** s
19390 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 tatement on the
193a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
193b0 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 ion specified by
193c0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
193d0 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 ter..** ^Executi
193e0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 ng any other typ
193f0 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 e of SQL stateme
19400 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 nt does not modi
19410 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 fy the value.**
19420 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 returned by this
19430 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
19440 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d ^Only changes m
19450 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 ade directly by
19460 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 the INSERT, UPDA
19470 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 TE or DELETE sta
19480 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f tement are.** co
19490 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c nsidered - auxil
194a0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 iary changes cau
194b0 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 sed by [CREATE T
194c0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 RIGGER | trigger
194d0 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e s], .** [foreign
194e0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 key actions] or
194f0 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 [REPLACE] const
19500 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e raint resolution
19510 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
19520 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 ..** .** Changes
19530 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 to a view that
19540 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 are intercepted
19550 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 by .** [INSTEAD
19560 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 OF trigger | INS
19570 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 TEAD OF triggers
19580 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 ] are not counte
19590 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a d. ^The value .*
195a0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 * returned by sq
195b0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
195c0 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 immediately afte
195d0 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 r an INSERT, UPD
195e0 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 ATE or .** DELET
195f0 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 E statement run
19600 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 on a view is alw
19610 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 ays zero. Only c
19620 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 hanges made to r
19630 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 eal .** tables a
19640 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a re counted..**.*
19650 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 * Things are mor
19660 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 e complicated if
19670 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 the sqlite3_cha
19680 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 nges() function
19690 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 is.** executed w
196a0 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 hile a trigger p
196b0 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e rogram is runnin
196c0 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 g. This may happ
196d0 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f en if the.** pro
196e0 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 gram uses the [c
196f0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e hanges() SQL fun
19700 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f ction], or if so
19710 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 me other callbac
19720 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e k.** function in
19730 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 vokes sqlite3_ch
19740 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 anges() directly
19750 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a . Essentially:.*
19760 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 * .** <ul>.**
19770 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e <li> ^(Before en
19780 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 tering a trigger
19790 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c program the val
197a0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ue returned by.*
197b0 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 * sqlite3
197c0 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 _changes() funct
197d0 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 ion is saved. Af
197e0 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20 ter the trigger
197f0 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 program .**
19800 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c has finished,
19810 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 the original va
19820 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e lue is restored.
19830 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e )^.** .** <li>
19840 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 ^(Within a trig
19850 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 ger program each
19860 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 INSERT, UPDATE
19870 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 and DELETE .**
19880 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 statement
19890 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 sets the value r
198a0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
198b0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a e3_changes() .**
198c0 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d upon com
198d0 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 pletion as norma
198e0 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 l. Of course, th
198f0 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f is value will no
19900 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 t include .**
19910 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 any changes
19920 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 performed by su
19930 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 b-triggers, as t
19940 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 he sqlite3_chang
19950 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 es() .**
19960 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 value will be sa
19970 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 ved and restored
19980 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d after each sub-
19990 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e trigger has run.
199a0 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a )^.** </ul>.** .
199b0 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 ** ^This means t
199c0 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 hat if the chang
199d0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f es() SQL functio
199e0 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 n (or similar) i
199f0 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 s used.** by the
19a00 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 first INSERT, U
19a10 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 PDATE or DELETE
19a20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e statement within
19a30 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a a trigger, it .
19a40 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 ** returns the v
19a50 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e alue as set when
19a60 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 the calling sta
19a70 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 tement began exe
19a80 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 cuting..** ^If i
19a90 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 t is used by the
19aa0 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 second or subse
19ab0 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 quent such state
19ac0 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 ment within a tr
19ad0 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 igger .** progra
19ae0 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 m, the value ret
19af0 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 urned reflects t
19b00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 he number of row
19b10 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 s modified by th
19b20 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 e .** previous I
19b30 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 NSERT, UPDATE or
19b40 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
19b50 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d t within the sam
19b60 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a e trigger..**.**
19b70 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
19b80 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
19b90 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
19ba0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 e, the.** [count
19bb0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d _changes pragma]
19bc0 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 , and the [chang
19bd0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f es() SQL functio
19be0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 n]..**.** If a s
19bf0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d eparate thread m
19c00 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 akes changes on
19c10 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
19c20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
19c30 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 while [sqlite3_c
19c40 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e hanges()] is run
19c50 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 ning then the va
19c60 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 lue returned.**
19c70 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 is unpredictable
19c80 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 and not meaning
19c90 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ful..*/.SQLITE_A
19ca0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 PI int SQLITE_AP
19cb0 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 68 ICALL sqlite3_ch
19cc0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b anges(sqlite3*);
19cd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
19ce0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f : Total Number O
19cf0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a f Rows Modified.
19d00 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
19d10 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 e3.**.** ^This f
19d20 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
19d30 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 the total number
19d40 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 of rows inserte
19d50 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a d, modified or.*
19d60 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c * deleted by all
19d70 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 [INSERT], [UPDA
19d80 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 TE] or [DELETE]
19d90 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c statements compl
19da0 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 eted.** since th
19db0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
19dc0 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 ction was opened
19dd0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 , including thos
19de0 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a e executed as.**
19df0 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 part of trigger
19e00 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 programs. ^Exec
19e10 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 uting any other
19e20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 type of SQL stat
19e30 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f ement.** does no
19e40 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c t affect the val
19e50 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
19e60 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
19e70 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e nges()..** .** ^
19e80 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 Changes made as
19e90 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e part of [foreign
19ea0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 key actions] ar
19eb0 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 e included in th
19ec0 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 e.** count, but
19ed0 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 those made as pa
19ee0 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f rt of REPLACE co
19ef0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 nstraint resolut
19f00 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 ion are.** not.
19f10 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 ^Changes to a vi
19f20 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 ew that are inte
19f30 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 rcepted by INSTE
19f40 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a AD OF triggers .
19f50 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 ** are not count
19f60 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 ed..** .** See a
19f70 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
19f80 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 _changes()] inte
19f90 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 rface, the.** [c
19fa0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 ount_changes pra
19fb0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 gma], and the [t
19fc0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 otal_changes() S
19fd0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
19fe0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
19ff0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
1a000 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
1a010 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
1a020 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
1a030 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
1a040 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e hanges()] is run
1a050 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 ning then the va
1a060 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lue.** returned
1a070 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 is unpredictable
1a080 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 and not meaning
1a090 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ful..*/.SQLITE_A
1a0a0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 PI int SQLITE_AP
1a0b0 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 6f ICALL sqlite3_to
1a0c0 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 tal_changes(sqli
1a0d0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
1a0e0 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 PI3REF: Interrup
1a0f0 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 t A Long-Running
1a100 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 Query.** METHOD
1a110 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
1a120 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 ^This function c
1a130 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e auses any pendin
1a140 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 g database opera
1a150 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e tion to abort an
1a160 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 d.** return at i
1a170 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f ts earliest oppo
1a180 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f rtunity. This ro
1a190 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c utine is typical
1a1a0 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 ly.** called in
1a1b0 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 response to a us
1a1c0 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 er action such a
1a1d0 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 s pressing "Canc
1a1e0 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 el".** or Ctrl-C
1a1f0 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 where the user
1a200 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 wants a long que
1a210 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 ry operation to
1a220 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 halt.** immediat
1a230 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 ely..**.** ^It i
1a240 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 s safe to call t
1a250 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d his routine from
1a260 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 a thread differ
1a270 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 ent from the.**
1a280 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 thread that is c
1a290 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 urrently running
1a2a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 the database op
1a2b0 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 eration. But it
1a2c0 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 .** is not safe
1a2d0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 to call this rou
1a2e0 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 tine with a [dat
1a2f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1a300 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f ] that.** is clo
1a310 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f sed or might clo
1a320 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 se before sqlite
1a330 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 3_interrupt() re
1a340 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 turns..**.** ^If
1a350 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f an SQL operatio
1a360 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 n is very nearly
1a370 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 finished at the
1a380 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 time when.** sq
1a390 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1a3a0 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 ) is called, the
1a3b0 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 n it might not h
1a3c0 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 ave an opportuni
1a3d0 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 ty.** to be inte
1a3e0 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 rrupted and migh
1a3f0 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f t continue to co
1a400 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 mpletion..**.**
1a410 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f ^An SQL operatio
1a420 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 n that is interr
1a430 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 upted will retur
1a440 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 n [SQLITE_INTERR
1a450 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 UPT]..** ^If the
1a460 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c interrupted SQL
1a470 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e operation is an
1a480 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
1a490 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 or DELETE.** th
1a4a0 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 at is inside an
1a4b0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 explicit transac
1a4c0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 tion, then the e
1a4d0 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f ntire transactio
1a4e0 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c n.** will be rol
1a4f0 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 led back automat
1a500 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ically..**.** ^T
1a510 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
1a520 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 rupt(D) call is
1a530 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 in effect until
1a540 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 all currently ru
1a550 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 nning.** SQL sta
1a560 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 tements on [data
1a570 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1a580 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 D complete. ^A
1a590 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 ny new SQL state
1a5a0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 ments.** that ar
1a5b0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 e started after
1a5c0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
1a5d0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 rrupt() call and
1a5e0 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 before the .**
1a5f0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e running statemen
1a600 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 ts reaches zero
1a610 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 are interrupted
1a620 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 as if they had b
1a630 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 een.** running p
1a640 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 rior to the sqli
1a650 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
1a660 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 call. ^New SQL
1a670 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
1a680 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 at are started a
1a690 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 fter the running
1a6a0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 statement count
1a6b0 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 reaches zero ar
1a6c0 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 e.** not effecte
1a6d0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 d by the sqlite3
1a6e0 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a _interrupt()..**
1a6f0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ^A call to sqli
1a700 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 te3_interrupt(D)
1a710 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 that occurs whe
1a720 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 n there are no r
1a730 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 unning.** SQL st
1a740 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f atements is a no
1a750 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 -op and has no e
1a760 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 ffect on SQL sta
1a770 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 tements.** that
1a780 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 are started afte
1a790 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e r the sqlite3_in
1a7a0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 terrupt() call r
1a7b0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 eturns..**.** If
1a7c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
1a7d0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 nnection closes
1a7e0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 while [sqlite3_i
1a7f0 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 nterrupt()].** i
1a800 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 s running then b
1a810 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c ad things will l
1a820 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f ikely happen..*/
1a830 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
1a840 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 SQLITE_APICALL
1a850 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
1a860 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a t(sqlite3*);../*
1a870 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
1a880 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 termine If An SQ
1a890 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 L Statement Is C
1a8a0 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 omplete.**.** Th
1a8b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
1a8c0 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 useful during c
1a8d0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 ommand-line inpu
1a8e0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 t to determine i
1a8f0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 f the.** current
1a900 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 ly entered text
1a910 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 seems to form a
1a920 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 complete SQL sta
1a930 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 tement or.** if
1a940 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 additional input
1a950 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 is needed befor
1a960 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 e sending the te
1a970 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 xt into.** SQLit
1a980 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 e for parsing.
1a990 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
1a9a0 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 return 1 if the
1a9b0 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 input string.**
1a9c0 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 appears to be a
1a9d0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 complete SQL sta
1a9e0 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 tement. ^A stat
1a9f0 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 ement is judged
1aa00 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 to be.** complet
1aa10 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 e if it ends wit
1aa20 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f h a semicolon to
1aa30 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 ken and is not a
1aa40 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 prefix of a.**
1aa50 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 well-formed CREA
1aa60 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 TE TRIGGER state
1aa70 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f ment. ^Semicolo
1aa80 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 ns that are embe
1aa90 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 dded within.** s
1aaa0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f tring literals o
1aab0 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 r quoted identif
1aac0 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d ier names or com
1aad0 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a ments are not.**
1aae0 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b independent tok
1aaf0 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 ens (they are pa
1ab00 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 rt of the token
1ab10 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 in which they ar
1ab20 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 e.** embedded) a
1ab30 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 nd thus do not c
1ab40 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d ount as a statem
1ab50 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ent terminator.
1ab60 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 ^Whitespace.**
1ab70 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 and comments tha
1ab80 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e t follow the fin
1ab90 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 al semicolon are
1aba0 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 ignored..**.**
1abb0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
1abc0 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 return 0 if the
1abd0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 statement is inc
1abe0 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a omplete. ^If a.
1abf0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
1ac00 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e tion fails, then
1ac10 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 SQLITE_NOMEM is
1ac20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
1ac30 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
1ac40 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 do not parse th
1ac50 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
1ac60 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f thus.** will no
1ac70 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 t detect syntact
1ac80 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 ically incorrect
1ac90 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 SQL..**.** ^(If
1aca0 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 SQLite has not
1acb0 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 been initialized
1acc0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
1acd0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 initialize()] pr
1ace0 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b ior .** to invok
1acf0 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 ing sqlite3_comp
1ad00 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 lete16() then sq
1ad10 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
1ad20 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a () is invoked.**
1ad30 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 automatically b
1ad40 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 y sqlite3_comple
1ad50 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 te16(). If that
1ad60 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
1ad70 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 fails,.** then t
1ad80 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
1ad90 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d from sqlite3_com
1ada0 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 plete16() will b
1adb0 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 e non-zero.** re
1adc0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
1add0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 her or not the i
1ade0 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 nput SQL is comp
1adf0 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 lete.)^.**.** Th
1ae00 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 e input to [sqli
1ae10 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 te3_complete()]
1ae20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 must be a zero-t
1ae30 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
1ae40 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a -8 string..**.**
1ae50 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 The input to [s
1ae60 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
1ae70 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 6()] must be a z
1ae80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
1ae90 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 * UTF-16 string
1aea0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f in native byte o
1aeb0 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f rder..*/.SQLITE_
1aec0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 API int SQLITE_A
1aed0 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 PICALL sqlite3_c
1aee0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 omplete(const ch
1aef0 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 ar *sql);.SQLITE
1af00 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
1af10 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f APICALL sqlite3_
1af20 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 complete16(const
1af30 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a void *sql);../*
1af40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
1af50 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 gister A Callbac
1af60 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 k To Handle SQLI
1af70 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a TE_BUSY Errors.*
1af80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 * KEYWORDS: {bus
1af90 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 y-handler callba
1afa0 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 ck} {busy handle
1afb0 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 r}.** METHOD: sq
1afc0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 lite3.**.** ^The
1afd0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 sqlite3_busy_ha
1afe0 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 ndler(D,X,P) rou
1aff0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c tine sets a call
1b000 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a back function X.
1b010 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 ** that might be
1b020 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 invoked with ar
1b030 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 gument P wheneve
1b040 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 r.** an attempt
1b050 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 is made to acces
1b060 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 s a database tab
1b070 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 le associated wi
1b080 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 th.** [database
1b090 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 connection] D wh
1b0a0 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 en another threa
1b0b0 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 d.** or process
1b0c0 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f has the table lo
1b0d0 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c cked..** The sql
1b0e0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
1b0f0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 r() interface is
1b100 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 used to impleme
1b110 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 nt.** [sqlite3_b
1b120 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 usy_timeout()] a
1b130 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f nd [PRAGMA busy_
1b140 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 timeout]..**.**
1b150 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c ^If the busy cal
1b160 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 lback is NULL, t
1b170 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 hen [SQLITE_BUSY
1b180 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 ].** is returned
1b190 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f immediately upo
1b1a0 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 n encountering t
1b1b0 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 he lock. ^If th
1b1c0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a e busy callback.
1b1d0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 ** is not NULL,
1b1e0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 then the callbac
1b1f0 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b k might be invok
1b200 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 ed with two argu
1b210 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ments..**.** ^Th
1b220 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1b230 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e to the busy han
1b240 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f dler is a copy o
1b250 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e f the void* poin
1b260 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ter which.** is
1b270 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
1b280 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 nt to sqlite3_bu
1b290 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e sy_handler(). ^
1b2a0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
1b2b0 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 ent to.** the bu
1b2c0 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 sy handler callb
1b2d0 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ack is the numbe
1b2e0 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 r of times that
1b2f0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
1b300 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 has.** been inv
1b310 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 oked previously
1b320 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 for the same loc
1b330 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 king event. ^If
1b340 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c the.** busy cal
1b350 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c lback returns 0,
1b360 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f then no additio
1b370 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 nal attempts are
1b380 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 made to.** acce
1b390 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
1b3a0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 and [SQLITE_BUSY
1b3b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a ] is returned.**
1b3c0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 to the applicat
1b3d0 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ion..** ^If the
1b3e0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
1b3f0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 non-zero, then
1b400 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a another attempt.
1b410 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 ** is made to ac
1b420 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 cess the databas
1b430 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 e and the cycle
1b440 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 repeats..**.** T
1b450 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 he presence of a
1b460 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f busy handler do
1b470 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 es not guarantee
1b480 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 that it will be
1b490 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e invoked.** when
1b4a0 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 there is lock c
1b4b0 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 ontention. ^If S
1b4c0 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 QLite determines
1b4d0 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 that invoking t
1b4e0 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c he busy.** handl
1b4f0 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 er could result
1b500 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 in a deadlock, i
1b510 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 t will go ahead
1b520 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 and return [SQLI
1b530 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 TE_BUSY].** to t
1b540 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 he application i
1b550 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 nstead of invoki
1b560 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 ng the .** busy
1b570 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 handler..** Cons
1b580 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 ider a scenario
1b590 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 where one proces
1b5a0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 s is holding a r
1b5b0 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a ead lock that.**
1b5c0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f it is trying to
1b5d0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 promote to a re
1b5e0 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a served lock and.
1b5f0 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 ** a second proc
1b600 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 ess is holding a
1b610 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 reserved lock t
1b620 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 hat it is trying
1b630 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 .** to promote t
1b640 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c o an exclusive l
1b650 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 ock. The first
1b660 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 process cannot p
1b670 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 roceed.** becaus
1b680 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 e it is blocked
1b690 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e by the second an
1b6a0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f d the second pro
1b6b0 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 cess cannot.** p
1b6c0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 roceed because i
1b6d0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 t is blocked by
1b6e0 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 the first. If b
1b6f0 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a oth processes.**
1b700 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 invoke the busy
1b710 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 handlers, neith
1b720 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 er will make any
1b730 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 progress. Ther
1b740 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 efore,.** SQLite
1b750 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
1b760 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 _BUSY] for the f
1b770 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f irst process, ho
1b780 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a ping that this.*
1b790 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 * will induce th
1b7a0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 e first process
1b7b0 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 to release its r
1b7c0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c ead lock and all
1b7d0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 ow.** the second
1b7e0 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 process to proc
1b7f0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 eed..**.** ^The
1b800 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c default busy cal
1b810 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a lback is NULL..*
1b820 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e *.** ^(There can
1b830 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c only be a singl
1b840 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 e busy handler d
1b850 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a efined for each.
1b860 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
1b870 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 nection]. Setti
1b880 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 ng a new busy ha
1b890 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 ndler clears any
1b8a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
1b8b0 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e et handler.)^ ^
1b8c0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e Note that callin
1b8d0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
1b8e0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 timeout()].** or
1b8f0 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 evaluating [PRA
1b900 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 GMA busy_timeout
1b910 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 =N] will change
1b920 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 the.** busy hand
1b930 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 ler and thus cle
1b940 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c ar any previousl
1b950 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c y set busy handl
1b960 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 er..**.** The bu
1b970 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 sy callback shou
1b980 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 ld not take any
1b990 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f actions which mo
1b9a0 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 dify the.** data
1b9b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1b9c0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
1b9d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 busy handler.
1b9e0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a In other words,.
1b9f0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ** the busy hand
1ba00 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 ler is not reent
1ba10 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 rant. Any such
1ba20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c actions.** resul
1ba30 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 t in undefined b
1ba40 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 ehavior..** .**
1ba50 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d A busy handler m
1ba60 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 ust not close th
1ba70 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1ba80 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 ction.** or [pre
1ba90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1baa0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
1bab0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a e busy handler..
1bac0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
1bad0 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c t SQLITE_APICALL
1bae0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 sqlite3_busy_ha
1baf0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 ndler(sqlite3*,
1bb00 69 6e 74 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 int(SQLITE_CALLB
1bb10 41 43 4b 20 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 ACK *)(void*,int
1bb20 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ), void*);../*.*
1bb30 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 * CAPI3REF: Set
1bb40 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a A Busy Timeout.*
1bb50 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
1bb60 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 3.**.** ^This ro
1bb70 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 utine sets a [sq
1bb80 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
1bb90 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 er | busy handle
1bba0 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a r] that sleeps.*
1bbb0 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 * for a specifie
1bbc0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 d amount of time
1bbd0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 when a table is
1bbe0 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 locked. ^The h
1bbf0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 andler.** will s
1bc00 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 leep multiple ti
1bc10 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 mes until at lea
1bc20 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 st "ms" millisec
1bc30 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
1bc40 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c .** have accumul
1bc50 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 ated. ^After at
1bc60 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c least "ms" mill
1bc70 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 iseconds of slee
1bc80 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e ping,.** the han
1bc90 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 dler returns 0 w
1bca0 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c hich causes [sql
1bcb0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 ite3_step()] to
1bcc0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 return.** [SQLIT
1bcd0 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e E_BUSY]..**.** ^
1bce0 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 Calling this rou
1bcf0 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 tine with an arg
1bd00 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 ument less than
1bd10 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f or equal to zero
1bd20 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c .** turns off al
1bd30 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e l busy handlers.
1bd40 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 .**.** ^(There c
1bd50 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e an only be a sin
1bd60 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 gle busy handler
1bd70 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
1bd80 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
1bd90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e onnection] at an
1bda0 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 y given moment.
1bdb0 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 If another busy
1bdc0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 handler.** was
1bdd0 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 defined (using
1bde0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 [sqlite3_busy_ha
1bdf0 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 ndler()]) prior
1be00 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 to calling.** th
1be10 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 is routine, that
1be20 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 other busy hand
1be30 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 ler is cleared.)
1be40 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ^.**.** See also
1be50 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f : [PRAGMA busy_
1be60 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49 timeout].*/.SQLI
1be70 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
1be80 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 E_APICALL sqlite
1be90 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 3_busy_timeout(s
1bea0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 qlite3*, int ms)
1beb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1bec0 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 F: Convenience R
1bed0 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e outines For Runn
1bee0 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d ing Queries.** M
1bef0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
1bf00 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c *.** This is a l
1bf10 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 egacy interface
1bf20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 that is preserve
1bf30 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 d for backwards
1bf40 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a compatibility..*
1bf50 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e * Use of this in
1bf60 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 terface is not r
1bf70 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a ecommended..**.*
1bf80 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 * Definition: A
1bf90 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c <b>result table<
1bfa0 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 /b> is memory da
1bfb0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 ta structure cre
1bfc0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b ated by the.** [
1bfd0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
1bfe0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 e()] interface.
1bff0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
1c000 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 records the.** c
1c010 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 omplete query re
1c020 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f sults from one o
1c030 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a r more queries..
1c040 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 **.** The table
1c050 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 conceptually has
1c060 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 a number of row
1c070 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 s and columns.
1c080 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d But.** these num
1c090 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 bers are not par
1c0a0 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 t of the result
1c0b0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 table itself. T
1c0c0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 hese.** numbers
1c0d0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 are obtained sep
1c0e0 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 arately. Let N
1c0f0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 be the number of
1c100 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 rows.** and M b
1c110 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 e the number of
1c120 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 columns..**.** A
1c130 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 result table is
1c140 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
1c150 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 nters to zero-te
1c160 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
1c170 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 trings..** There
1c180 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 are (N+1)*M ele
1c190 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 ments in the arr
1c1a0 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d ay. The first M
1c1b0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a pointers point.
1c1c0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 ** to zero-termi
1c1d0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 nated strings th
1c1e0 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 at contain the
1c1f0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c names of the col
1c200 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d umns..** The rem
1c210 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 aining entries a
1c220 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 ll point to quer
1c230 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c y results. NULL
1c240 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a values result.*
1c250 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 * in NULL pointe
1c260 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 rs. All other v
1c270 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 alues are in the
1c280 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 ir UTF-8 zero-te
1c290 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 rminated.** stri
1c2a0 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f ng representatio
1c2b0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 n as returned by
1c2c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
1c2d0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _text()]..**.**
1c2e0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d A result table m
1c2f0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 ight consist of
1c300 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f one or more memo
1c310 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a ry allocations..
1c320 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 ** It is not saf
1c330 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 e to pass a resu
1c340 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c lt table directl
1c350 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 y to [sqlite3_fr
1c360 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 ee()]..** A resu
1c370 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 lt table should
1c380 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 be deallocated u
1c390 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 sing [sqlite3_fr
1c3a0 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a ee_table()]..**.
1c3b0 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 ** ^(As an examp
1c3c0 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 le of the result
1c3d0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 table format, s
1c3e0 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 uppose a query r
1c3f0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 esult.** is as f
1c400 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
1c410 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1c420 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 ** Name
1c430 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 | Age.**
1c440 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------
1c450 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a -------------.**
1c460 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 Alice
1c470 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 | 43.**
1c480 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c Bob |
1c490 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 28.** Ci
1c4a0 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a ndy | 21.*
1c4b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1c4c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 uote>.**.** Ther
1c4d0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e e are two column
1c4e0 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 (M==2) and thre
1c4f0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 e rows (N==3).
1c500 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 Thus the.** resu
1c510 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 lt table has 8 e
1c520 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 ntries. Suppose
1c530 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
1c540 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 e is stored.** i
1c550 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 n an array names
1c560 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e azResult. Then
1c570 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 azResult holds
1c580 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a this content:.**
1c590 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1c5a0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <pre>.**
1c5b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 azResult[0]
1c5c0 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 = "Name";.**
1c5d0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1c5e0 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 ;1] = "Age";.**
1c5f0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1c600 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 #91;2] = "Alice"
1c610 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1c620 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 sult[3] = "4
1c630 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 3";.** az
1c640 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 Result[4] =
1c650 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 "Bob";.**
1c660 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d azResult[5]
1c670 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 = "28";.**
1c680 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1c690 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 6] = "Cindy";.**
1c6a0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1c6b0 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a [7] = "21";.
1c6c0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1c6d0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e quote>)^.**.** ^
1c6e0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
1c6f0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e table() function
1c700 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f evaluates one o
1c710 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f r more.** semico
1c720 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 lon-separated SQ
1c730 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 L statements in
1c740 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 the zero-termina
1c750 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 ted UTF-8.** str
1c760 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 ing of its 2nd p
1c770 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 arameter and ret
1c780 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 urns a result ta
1c790 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f ble to the.** po
1c7a0 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 inter given in i
1c7b0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 ts 3rd parameter
1c7c0 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 ..**.** After th
1c7d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 e application ha
1c7e0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 s finished with
1c7f0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 the result from
1c800 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
1c810 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 e(),.** it must
1c820 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 pass the result
1c830 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f table pointer to
1c840 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 sqlite3_free_ta
1c850 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 ble() in order t
1c860 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 o.** release the
1c870 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 memory that was
1c880 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 malloced. Beca
1c890 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 use of the way t
1c8a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d he.** [sqlite3_m
1c8b0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 alloc()] happens
1c8c0 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f within sqlite3_
1c8d0 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 get_table(), the
1c8e0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 calling.** func
1c8f0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 tion must not tr
1c900 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 y to call [sqlit
1c910 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 e3_free()] direc
1c920 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 tly. Only.** [s
1c930 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
1c940 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 e()] is able to
1c950 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f release the memo
1c960 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 ry properly and
1c970 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 safely..**.** Th
1c980 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
1c990 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ble() interface
1c9a0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 is implemented a
1c9b0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 s a wrapper arou
1c9c0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 nd.** [sqlite3_e
1c9d0 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c xec()]. The sql
1c9e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1c9f0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f routine does no
1ca00 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a t have access.**
1ca10 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c to any internal
1ca20 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 data structures
1ca30 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 of SQLite. It
1ca40 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 uses only the pu
1ca50 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 blic.** interfac
1ca60 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 e defined here.
1ca70 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 As a consequenc
1ca80 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f e, errors that o
1ca90 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 ccur in the.** w
1caa0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 rapper layer out
1cab0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 side of the inte
1cac0 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 rnal [sqlite3_ex
1cad0 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e ec()] call are n
1cae0 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 ot.** reflected
1caf0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 in subsequent ca
1cb00 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
1cb10 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a errcode()] or.**
1cb20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
1cb30 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
1cb40 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 PI int SQLITE_AP
1cb50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 65 ICALL sqlite3_ge
1cb60 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 t_table(. sqlit
1cb70 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
1cb80 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 /* An open data
1cb90 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 base */. const
1cba0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
1cbb0 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 /* SQL to be eva
1cbc0 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 luated */. char
1cbd0 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 ***pazResult,
1cbe0 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 /* Results of
1cbf0 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 the query */. i
1cc00 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 nt *pnRow,
1cc10 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f /* Number o
1cc20 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 f result rows wr
1cc30 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 itten here */.
1cc40 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 int *pnColumn,
1cc50 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 /* Number
1cc60 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e of result column
1cc70 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a s written here *
1cc80 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 /. char **pzErr
1cc90 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 msg /* Err
1cca0 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 or msg written h
1ccb0 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 ere */.);.SQLITE
1ccc0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 _API void SQLITE
1ccd0 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 _APICALL sqlite3
1cce0 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 _free_table(char
1ccf0 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a **result);../*.
1cd00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 ** CAPI3REF: For
1cd10 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 matted String Pr
1cd20 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 inting Functions
1cd30 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
1cd40 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 tines are work-a
1cd50 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 likes of the "pr
1cd60 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f intf()" family o
1cd70 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 f functions.** f
1cd80 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 rom the standard
1cd90 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 C library..** T
1cda0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e hese routines un
1cdb0 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 derstand most of
1cdc0 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 the common K&R
1cdd0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f formatting optio
1cde0 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 ns,.** plus some
1cdf0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d additional non-
1ce00 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 standard formats
1ce10 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 , detailed below
1ce20 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 ..** Note that s
1ce30 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 ome of the more
1ce40 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 obscure formatti
1ce50 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 ng options from
1ce60 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 recent.** C-libr
1ce70 61 72 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 ary standards ar
1ce80 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 e omitted from t
1ce90 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 his implementati
1cea0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 on..**.** ^The s
1ceb0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
1cec0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 and sqlite3_vmp
1ced0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 rintf() routines
1cee0 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 write their.**
1cef0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d results into mem
1cf00 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ory obtained fro
1cf10 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
1cf20 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 c()]..** The str
1cf30 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 ings returned by
1cf40 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 these two routi
1cf50 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a nes should be.**
1cf60 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 released by [sq
1cf70 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 lite3_free()].
1cf80 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 ^Both routines r
1cf90 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 eturn a.** NULL
1cfa0 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 pointer if [sqli
1cfb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 te3_malloc()] is
1cfc0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
1cfd0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 ate enough.** me
1cfe0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
1cff0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e resulting strin
1d000 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 g..**.** ^(The s
1d010 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1d020 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d ) routine is sim
1d030 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 ilar to "snprint
1d040 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 f()" from.** the
1d050 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 standard C libr
1d060 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 ary. The result
1d070 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
1d080 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 the.** buffer s
1d090 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 upplied as the s
1d0a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1d0b0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 whose size is gi
1d0c0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 ven by.** the fi
1d0d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e rst parameter. N
1d0e0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 ote that the ord
1d0f0 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 er of the.** fir
1d100 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 st two parameter
1d110 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 s is reversed fr
1d120 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e om snprintf().)^
1d130 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 This is an.**
1d140 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 historical accid
1d150 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 ent that cannot
1d160 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 be fixed without
1d170 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 breaking.** bac
1d180 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
1d190 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c lity. ^(Note al
1d1a0 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f so that sqlite3_
1d1b0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 snprintf().** re
1d1c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
1d1d0 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e to its buffer in
1d1e0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d stead of the num
1d1f0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 ber of.** charac
1d200 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 ters actually wr
1d210 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 itten into the b
1d220 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d uffer.)^ We adm
1d230 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e it that.** the n
1d240 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 umber of charact
1d250 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c ers written woul
1d260 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 d be a more usef
1d270 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c ul return.** val
1d280 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 ue but we cannot
1d290 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c change the impl
1d2a0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 ementation of sq
1d2b0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
1d2c0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 .** now without
1d2d0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 breaking compati
1d2e0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 bility..**.** ^A
1d2f0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 s long as the bu
1d300 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 ffer size is gre
1d310 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 ater than zero,
1d320 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1d330 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 ().** guarantees
1d340 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 that the buffer
1d350 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d is always zero-
1d360 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 terminated. ^Th
1d370 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d e first.** param
1d380 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 eter "n" is the
1d390 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 total size of th
1d3a0 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 e buffer, includ
1d3b0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a ing space for.**
1d3c0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e the zero termin
1d3d0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f ator. So the lo
1d3e0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 ngest string tha
1d3f0 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 t can be complet
1d400 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 ely.** written w
1d410 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 ill be n-1 chara
1d420 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 cters..**.** ^Th
1d430 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 e sqlite3_vsnpri
1d440 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ntf() routine is
1d450 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 a varargs versi
1d460 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e on of sqlite3_sn
1d470 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 printf()..**.**
1d480 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
1d490 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d ll implement som
1d4a0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 e additional for
1d4b0 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f matting.** optio
1d4c0 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 ns that are usef
1d4d0 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 ul for construct
1d4e0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ing SQL statemen
1d4f0 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 ts..** All of th
1d500 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 e usual printf()
1d510 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 formatting opti
1d520 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 ons apply. In a
1d530 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a ddition, there.*
1d540 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 * is are "%q", "
1d550 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 %Q", "%w" and "%
1d560 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a z" options..**.*
1d570 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f * ^(The %q optio
1d580 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 n works like %s
1d590 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 in that it subst
1d5a0 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 itutes a nul-ter
1d5b0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e minated.** strin
1d5c0 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d g from the argum
1d5d0 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 ent list. But %
1d5e0 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 q also doubles e
1d5f0 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 very '\'' charac
1d600 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 ter..** %q is de
1d610 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 signed for use i
1d620 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c nside a string l
1d630 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f iteral.)^ By do
1d640 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 ubling each '\''
1d650 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 .** character it
1d660 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 escapes that ch
1d670 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f aracter and allo
1d680 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 ws it to be inse
1d690 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 rted into.** the
1d6a0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 string..**.** F
1d6b0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 or example, assu
1d6c0 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 me the string va
1d6d0 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e riable zText con
1d6e0 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f tains text as fo
1d6f0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c llows:.**.** <bl
1d700 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1d710 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d * char *zText =
1d720 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 "It's a happy d
1d730 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c ay!";.** </pre><
1d740 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
1d750 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 ** One can use t
1d760 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 his text in an S
1d770 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 QL statement as
1d780 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
1d790 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1d7a0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 .** char *zSQL
1d7b0 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 = sqlite3_mprint
1d7c0 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 f("INSERT INTO t
1d7d0 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 able VALUES('%q'
1d7e0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 )", zText);.**
1d7f0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c sqlite3_exec(db,
1d800 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b zSQL, 0, 0, 0);
1d810 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 .** sqlite3_fre
1d820 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 e(zSQL);.** </pr
1d830 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1d840 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 **.** Because th
1d850 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 e %q format stri
1d860 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 ng is used, the
1d870 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 '\'' character i
1d880 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 n zText.** is es
1d890 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 caped and the SQ
1d8a0 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 L generated is a
1d8b0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
1d8c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1d8d0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e e>.** INSERT IN
1d8e0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 TO table1 VALUES
1d8f0 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 ('It''s a happy
1d900 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e day!').** </pre>
1d910 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1d920 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 .** This is corr
1d930 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 ect. Had we use
1d940 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 d %s instead of
1d950 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 %q, the generate
1d960 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 d SQL.** would h
1d970 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 ave looked like
1d980 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f this:.**.** <blo
1d990 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1d9a0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 INSERT INTO ta
1d9b0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 ble1 VALUES('It'
1d9c0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 s a happy day!')
1d9d0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
1d9e0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
1d9f0 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 his second examp
1da00 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e le is an SQL syn
1da10 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 tax error. As a
1da20 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f general rule yo
1da30 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 u should.** alwa
1da40 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 ys use %q instea
1da50 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 d of %s when ins
1da60 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f erting text into
1da70 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 a string litera
1da80 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 l..**.** ^(The %
1da90 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c Q option works l
1daa0 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 ike %q except it
1dab0 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c also adds singl
1dac0 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a e quotes around.
1dad0 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f ** the outside o
1dae0 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 f the total stri
1daf0 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c ng. Additionall
1db00 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 y, if the parame
1db10 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 ter in the.** ar
1db20 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 gument list is a
1db30 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 NULL pointer, %
1db40 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 Q substitutes th
1db50 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 e text "NULL" (w
1db60 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 ithout.** single
1db70 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c quotes).)^ So,
1db80 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e for example, on
1db90 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a e could say:.**.
1dba0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1dbb0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
1dbc0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 SQL = sqlite3_mp
1dbd0 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e rintf("INSERT IN
1dbe0 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 TO table VALUES(
1dbf0 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a %Q)", zText);.**
1dc00 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 sqlite3_exec(d
1dc10 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 b, zSQL, 0, 0, 0
1dc20 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 );.** sqlite3_f
1dc30 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f ree(zSQL);.** </
1dc40 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1dc50 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 >.**.** The code
1dc60 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 above will rend
1dc70 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c er a correct SQL
1dc80 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 statement in th
1dc90 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 e zSQL.** variab
1dca0 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a le even if the z
1dcb0 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 Text variable is
1dcc0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1dcd0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 .**.** ^(The "%w
1dce0 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 " formatting opt
1dcf0 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 ion is like "%q"
1dd00 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 except that it
1dd10 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 expects to.** be
1dd20 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 contained withi
1dd30 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 n double-quotes
1dd40 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c instead of singl
1dd50 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 e quotes, and it
1dd60 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 .** escapes the
1dd70 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 double-quote cha
1dd80 72 61 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f racter instead o
1dd90 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f f the single-quo
1dda0 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e te.** character.
1ddb0 29 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 )^ The "%w" for
1ddc0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 matting option i
1ddd0 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 s intended for s
1dde0 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a afely inserting.
1ddf0 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c ** table and col
1de00 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 umn names into a
1de10 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c constructed SQL
1de20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a statement..**.*
1de30 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 * ^(The "%z" for
1de40 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 matting option w
1de50 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 orks like "%s" b
1de60 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 ut with the.** a
1de70 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 ddition that aft
1de80 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 er the string ha
1de90 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 s been read and
1dea0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 copied into.** t
1deb0 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 he result, [sqli
1dec0 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 te3_free()] is c
1ded0 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 alled on the inp
1dee0 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a ut string.)^.*/.
1def0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 SQLITE_API char
1df00 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 *SQLITE_CDECL sq
1df10 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f lite3_mprintf(co
1df20 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a nst char*,...);.
1df30 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 SQLITE_API char
1df40 2a 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 *SQLITE_APICALL
1df50 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
1df60 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 (const char*, va
1df70 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 _list);.SQLITE_A
1df80 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f PI char *SQLITE_
1df90 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 73 6e CDECL sqlite3_sn
1dfa0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a printf(int,char*
1dfb0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e ,const char*, ..
1dfc0 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 .);.SQLITE_API c
1dfd0 68 61 72 20 2a 53 51 4c 49 54 45 5f 41 50 49 43 har *SQLITE_APIC
1dfe0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 ALL sqlite3_vsnp
1dff0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c rintf(int,char*,
1e000 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f const char*, va_
1e010 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 list);../*.** CA
1e020 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
1e030 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 llocation Subsys
1e040 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 tem.**.** The SQ
1e050 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 Lite core uses t
1e060 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 hese three routi
1e070 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 nes for all of i
1e080 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e ts own.** intern
1e090 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 al memory alloca
1e0a0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 tion needs. "Cor
1e0b0 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f e" in the previo
1e0c0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 us sentence.** d
1e0d0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 oes not include
1e0e0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d operating-system
1e0f0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d specific VFS im
1e100 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 plementation. T
1e110 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 he.** Windows VF
1e120 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 S uses native ma
1e130 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 lloc() and free(
1e140 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 ) for some opera
1e150 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 tions..**.** ^Th
1e160 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 e sqlite3_malloc
1e170 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
1e180 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
1e190 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 a block.** of me
1e1a0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 mory at least N
1e1b0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c bytes in length,
1e1c0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
1e1d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 parameter..** ^I
1e1e0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 f sqlite3_malloc
1e1f0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 () is unable to
1e200 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e obtain sufficien
1e210 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 t free.** memory
1e220 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e , it returns a N
1e230 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 ULL pointer. ^I
1e240 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
1e250 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f N to.** sqlite3_
1e260 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f malloc() is zero
1e270 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 or negative the
1e280 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 n sqlite3_malloc
1e290 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 () returns.** a
1e2a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
1e2b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1e2c0 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 _malloc64(N) rou
1e2d0 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 tine works just
1e2e0 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f like.** sqlite3_
1e2f0 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 malloc(N) except
1e300 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e that N is an un
1e310 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e signed 64-bit in
1e320 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a teger instead.**
1e330 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d of a signed 32-
1e340 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a bit integer..**.
1e350 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 ** ^Calling sqli
1e360 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 te3_free() with
1e370 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f a pointer previo
1e380 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a usly returned.**
1e390 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c by sqlite3_mall
1e3a0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f oc() or sqlite3_
1e3b0 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 realloc() releas
1e3c0 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 es that memory s
1e3d0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 o.** that it mig
1e3e0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e ht be reused. ^
1e3f0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 The sqlite3_free
1e400 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a () routine is.**
1e410 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 a no-op if is c
1e420 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c alled with a NUL
1e430 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 L pointer. Pass
1e440 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ing a NULL point
1e450 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 er.** to sqlite3
1e460 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c _free() is harml
1e470 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e ess. After bein
1e480 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a g freed, memory.
1e490 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 ** should neithe
1e4a0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 r be read nor wr
1e4b0 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 itten. Even rea
1e4c0 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 ding previously
1e4d0 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 freed.** memory
1e4e0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 might result in
1e4f0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 a segmentation f
1e500 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 ault or other se
1e510 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d vere error..** M
1e520 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e emory corruption
1e530 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e , a segmentation
1e540 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 fault, or other
1e550 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a severe error.**
1e560 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 might result if
1e570 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
1e580 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 is called with a
1e590 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
1e5a0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f r that.** was no
1e5b0 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 t obtained from
1e5c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1e5d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c or sqlite3_real
1e5e0 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 loc()..**.** ^Th
1e5f0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f e sqlite3_reallo
1e600 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 c(X,N) interface
1e610 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 attempts to res
1e620 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d ize a.** prior m
1e630 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1e640 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 X to be at leas
1e650 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 t N bytes..** ^I
1e660 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 f the X paramete
1e670 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 r to sqlite3_rea
1e680 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 lloc(X,N).** is
1e690 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
1e6a0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 hen its behavior
1e6b0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f is identical to
1e6c0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
1e6d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a te3_malloc(N)..*
1e6e0 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 * ^If the N para
1e6f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
1e700 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 _realloc(X,N) is
1e710 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 zero or.** nega
1e720 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 tive then the be
1e730 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c havior is exactl
1e740 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 y the same as ca
1e750 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 lling.** sqlite3
1e760 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 _free(X)..** ^sq
1e770 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
1e780 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 N) returns a poi
1e790 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 nter to a memory
1e7a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f allocation.** o
1e7b0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 f at least N byt
1e7c0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 es in size or NU
1e7d0 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 LL if insufficie
1e7e0 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 nt memory is ava
1e7f0 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d ilable..** ^If M
1e800 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 is the size of
1e810 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
1e820 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e tion, then min(N
1e830 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 ,M) bytes.** of
1e840 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
1e850 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 tion are copied
1e860 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 into the beginni
1e870 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 ng of buffer ret
1e880 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 urned.** by sqli
1e890 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1e8a0 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 and the prior a
1e8b0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 llocation is fre
1e8c0 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 ed..** ^If sqlit
1e8d0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 e3_realloc(X,N)
1e8e0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 returns NULL and
1e8f0 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 N is positive,
1e900 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f then the.** prio
1e910 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 r allocation is
1e920 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a not freed..**.**
1e930 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
1e940 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 alloc64(X,N) int
1e950 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 erfaces works th
1e960 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c e same as.** sql
1e970 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e ite3_realloc(X,N
1e980 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 ) except that N
1e990 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 is a 64-bit unsi
1e9a0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 gned integer ins
1e9b0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d tead.** of a 32-
1e9c0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
1e9d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 er..**.** ^If X
1e9e0 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f is a memory allo
1e9f0 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c cation previousl
1ea00 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
1ea10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1ea20 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c ,.** sqlite3_mal
1ea30 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 loc64(), sqlite3
1ea40 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 _realloc(), or s
1ea50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 qlite3_realloc64
1ea60 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 (), then.** sqli
1ea70 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 te3_msize(X) ret
1ea80 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 urns the size of
1ea90 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c that memory all
1eaa0 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 ocation in bytes
1eab0 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 ..** ^The value
1eac0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
1ead0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 te3_msize(X) mig
1eae0 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 ht be larger tha
1eaf0 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 n the number.**
1eb00 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 of bytes request
1eb10 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c ed when X was al
1eb20 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 located. ^If X
1eb30 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
1eb40 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 r then.** sqlite
1eb50 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 3_msize(X) retur
1eb60 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 ns zero. If X p
1eb70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 oints to somethi
1eb80 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a ng that is not.*
1eb90 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 * the beginning
1eba0 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 of memory alloca
1ebb0 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 tion, or if it p
1ebc0 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 oints to a forme
1ebd0 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d rly.** valid mem
1ebe0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 ory allocation t
1ebf0 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e hat has now been
1ec00 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 freed, then the
1ec10 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 behavior.** of
1ec20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 sqlite3_msize(X)
1ec30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e is undefined an
1ec40 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 d possibly harmf
1ec50 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d ul..**.** ^The m
1ec60 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 emory returned b
1ec70 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 y sqlite3_malloc
1ec80 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c (), sqlite3_real
1ec90 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 loc(),.** sqlite
1eca0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 3_malloc64(), an
1ecb0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f d sqlite3_reallo
1ecc0 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 c64().** is alwa
1ecd0 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 ys aligned to at
1ece0 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 least an 8 byte
1ecf0 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f boundary, or to
1ed00 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 a.** 4 byte bou
1ed10 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 ndary if the [SQ
1ed20 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 LITE_4_BYTE_ALIG
1ed30 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 NED_MALLOC] comp
1ed40 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 ile-time.** opti
1ed50 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a on is used..**.*
1ed60 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 * In SQLite vers
1ed70 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e ion 3.5.0 and 3.
1ed80 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 5.1, it was poss
1ed90 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a ible to define.*
1eda0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 * the SQLITE_OMI
1edb0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 T_MEMORY_ALLOCAT
1edc0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 ION which would
1edd0 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d cause the built-
1ede0 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 in.** implementa
1edf0 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f tion of these ro
1ee00 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 utines to be omi
1ee10 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 tted. That capa
1ee20 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 bility.** is no
1ee30 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e longer provided.
1ee40 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 Only built-in
1ee50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
1ee60 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a s can be used..*
1ee70 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 *.** Prior to SQ
1ee80 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 Lite version 3.7
1ee90 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 .10, the Windows
1eea0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 OS interface la
1eeb0 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 yer called.** th
1eec0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 e system malloc(
1eed0 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 ) and free() dir
1eee0 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 ectly when conve
1eef0 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d rting.** filenam
1ef00 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 es between the U
1ef10 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 TF-8 encoding us
1ef20 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ed by SQLite.**
1ef30 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c and whatever fil
1ef40 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 ename encoding i
1ef50 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 s used by the pa
1ef60 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 rticular Windows
1ef70 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e .** installation
1ef80 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 . Memory alloca
1ef90 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 tion errors were
1efa0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a detected, but.*
1efb0 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f * they were repo
1efc0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 rted back as [SQ
1efd0 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f LITE_CANTOPEN] o
1efe0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 r.** [SQLITE_IOE
1eff0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 RR] rather than
1f000 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a [SQLITE_NOMEM]..
1f010 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 **.** The pointe
1f020 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b r arguments to [
1f030 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
1f040 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 and [sqlite3_rea
1f050 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 lloc()].** must
1f060 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f be either NULL o
1f070 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 r else pointers
1f080 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 obtained from a
1f090 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 prior.** invocat
1f0a0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
1f0b0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 malloc()] or [sq
1f0c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
1f0d0 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f that have.** no
1f0e0 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 t yet been relea
1f0f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 sed..**.** The a
1f100 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
1f110 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 not read or writ
1f120 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a e any part of.**
1f130 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f a block of memo
1f140 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 ry after it has
1f150 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 been released us
1f160 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
1f170 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 free()] or [sqli
1f180 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a te3_realloc()]..
1f190 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
1f1a0 69 64 20 2a 53 51 4c 49 54 45 5f 41 50 49 43 41 id *SQLITE_APICA
1f1b0 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f LL sqlite3_mallo
1f1c0 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 c(int);.SQLITE_A
1f1d0 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f PI void *SQLITE_
1f1e0 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f APICALL sqlite3_
1f1f0 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 malloc64(sqlite3
1f200 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 _uint64);.SQLITE
1f210 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 _API void *SQLIT
1f220 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 E_APICALL sqlite
1f230 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 3_realloc(void*,
1f240 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
1f250 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 41 I void *SQLITE_A
1f260 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 PICALL sqlite3_r
1f270 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 ealloc64(void*,
1f280 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b sqlite3_uint64);
1f290 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
1f2a0 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 SQLITE_APICALL
1f2b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 sqlite3_free(voi
1f2c0 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 d*);.SQLITE_API
1f2d0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 53 sqlite3_uint64 S
1f2e0 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 QLITE_APICALL sq
1f2f0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 lite3_msize(void
1f300 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1f310 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
1f320 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 cator Statistics
1f330 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 .**.** SQLite pr
1f340 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f ovides these two
1f350 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 interfaces for
1f360 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 reporting on the
1f370 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 status.** of th
1f380 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f e [sqlite3_mallo
1f390 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 c()], [sqlite3_f
1f3a0 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c ree()], and [sql
1f3b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a ite3_realloc()].
1f3c0 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 ** routines, whi
1f3d0 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c ch form the buil
1f3e0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f t-in memory allo
1f3f0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d cation subsystem
1f400 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 ..**.** ^The [sq
1f410 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
1f420 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 d()] routine ret
1f430 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
1f440 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d of bytes.** of m
1f450 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 emory currently
1f460 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c outstanding (mal
1f470 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 loced but not fr
1f480 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 eed)..** ^The [s
1f490 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
1f4a0 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 ghwater()] routi
1f4b0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d ne returns the m
1f4c0 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 aximum.** value
1f4d0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f of [sqlite3_memo
1f4e0 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 ry_used()] since
1f4f0 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 the high-water
1f500 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 mark.** was last
1f510 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 reset. ^The va
1f520 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 lues returned by
1f530 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1f540 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 _used()] and.**
1f550 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
1f560 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 highwater()] inc
1f570 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 lude any overhea
1f580 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 d.** added by SQ
1f590 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c Lite in its impl
1f5a0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 ementation of [s
1f5b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
1f5c0 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 ,.** but not ove
1f5d0 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 rhead added by t
1f5e0 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e he any underlyin
1f5f0 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 g system library
1f600 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 .** routines tha
1f610 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f t [sqlite3_mallo
1f620 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a c()] may call..*
1f630 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 *.** ^The memory
1f640 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b high-water mark
1f650 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 is reset to the
1f660 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f current value o
1f670 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 f.** [sqlite3_me
1f680 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 mory_used()] if
1f690 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 and only if the
1f6a0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
1f6b0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
1f6c0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 highwater()] is
1f6d0 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 true. ^The valu
1f6e0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 e returned.** by
1f6f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1f700 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 _highwater(1)] i
1f710 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 s the high-water
1f720 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 mark.** prior t
1f730 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a o the reset..*/.
1f740 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
1f750 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f e3_int64 SQLITE_
1f760 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f APICALL sqlite3_
1f770 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 memory_used(void
1f780 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 );.SQLITE_API sq
1f790 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 lite3_int64 SQLI
1f7a0 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 TE_APICALL sqlit
1f7b0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
1f7c0 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 ter(int resetFla
1f7d0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 g);../*.** CAPI3
1f7e0 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 REF: Pseudo-Rand
1f7f0 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 om Number Genera
1f800 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 tor.**.** SQLite
1f810 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 contains a high
1f820 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d -quality pseudo-
1f830 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 random number ge
1f840 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 nerator (PRNG) u
1f850 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 sed to.** select
1f860 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c random [ROWID |
1f870 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e ROWIDs] when in
1f880 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f serting new reco
1f890 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 rds into a table
1f8a0 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 that.** already
1f8b0 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 uses the larges
1f8c0 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 t possible [ROWI
1f8d0 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 D]. The PRNG is
1f8e0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a also used for.*
1f8f0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 * the build-in r
1f900 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 andom() and rand
1f910 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e omblob() SQL fun
1f920 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e ctions. This in
1f930 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a terface allows.*
1f940 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 * applications t
1f950 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d o access the sam
1f960 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 e PRNG for other
1f970 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a purposes..**.**
1f980 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 ^A call to this
1f990 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 routine stores
1f9a0 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f N bytes of rando
1f9b0 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 mness into buffe
1f9c0 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 r P..** ^The P p
1f9d0 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 arameter can be
1f9e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
1f9f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 **.** ^If this r
1fa00 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 outine has not b
1fa10 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 een previously c
1fa20 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 alled or if the
1fa30 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c previous.** call
1fa40 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e had N less than
1fa50 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 one or a NULL p
1fa60 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 ointer for P, th
1fa70 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a en the PRNG is.*
1fa80 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 * seeded using r
1fa90 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e andomness obtain
1faa0 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e ed from the xRan
1fab0 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f domness method o
1fac0 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 f.** the default
1fad0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
1fae0 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 bject..** ^If th
1faf0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 e previous call
1fb00 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 to this routine
1fb10 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 had an N of 1 or
1fb20 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e more and a.** n
1fb30 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 on-NULL P then t
1fb40 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d he pseudo-random
1fb50 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 ness is generate
1fb60 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 d.** internally
1fb70 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f and without reco
1fb80 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c urse to the [sql
1fb90 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f ite3_vfs] xRando
1fba0 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e mness.** method.
1fbb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
1fbc0 6f 69 64 20 53 51 4c 49 54 45 5f 41 50 49 43 41 oid SQLITE_APICA
1fbd0 4c 4c 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f LL sqlite3_rando
1fbe0 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 mness(int N, voi
1fbf0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 d *P);../*.** CA
1fc00 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d PI3REF: Compile-
1fc10 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 Time Authorizati
1fc20 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 on Callbacks.**
1fc30 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
1fc40 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
1fc50 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e ine registers an
1fc60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1fc70 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 back with a part
1fc80 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
1fc90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c ase connection],
1fca0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 supplied in the
1fcb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
1fcc0 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 .** ^The authori
1fcd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
1fce0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 invoked as SQL s
1fcf0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 tatements are be
1fd00 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 ing compiled.**
1fd10 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 by [sqlite3_prep
1fd20 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 are()] or its va
1fd30 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f riants [sqlite3_
1fd40 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a prepare_v2()],.*
1fd50 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
1fd60 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c re16()] and [sql
1fd70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1fd80 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 2()]. ^At vario
1fd90 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 us.** points dur
1fda0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 ing the compilat
1fdb0 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 ion process, as
1fdc0 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 logic is being c
1fdd0 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 reated.** to per
1fde0 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 form various act
1fdf0 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 ions, the author
1fe00 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
1fe10 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 invoked to.** s
1fe20 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 ee if those acti
1fe30 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e ons are allowed.
1fe40 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 ^The authorize
1fe50 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c r callback shoul
1fe60 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c d.** return [SQL
1fe70 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 ITE_OK] to allow
1fe80 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 the action, [SQ
1fe90 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 LITE_IGNORE] to
1fea0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 disallow the.**
1feb0 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 specific action
1fec0 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 but allow the SQ
1fed0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 L statement to c
1fee0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a ontinue to be.**
1fef0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 compiled, or [S
1ff00 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 QLITE_DENY] to c
1ff10 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 ause the entire
1ff20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f SQL statement to
1ff30 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 be.** rejected
1ff40 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 with an error.
1ff50 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a ^If the authoriz
1ff60 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 er callback retu
1ff70 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 rns.** any value
1ff80 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
1ff90 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 ITE_IGNORE], [SQ
1ffa0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 LITE_OK], or [SQ
1ffb0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 LITE_DENY].** th
1ffc0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f en the [sqlite3_
1ffd0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
1ffe0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c equivalent call
1fff0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a that triggered.
20000 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ** the authorize
20010 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 r will fail with
20020 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
20030 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 e..**.** When th
20040 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
20050 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ns [SQLITE_OK],
20060 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f that means the o
20070 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 peration.** requ
20080 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 ested is ok. ^W
20090 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
200a0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
200b0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b _DENY], the.** [
200c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
200d0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c v2()] or equival
200e0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ent call that tr
200f0 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 iggered the.** a
20100 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 uthorizer will f
20110 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f ail with an erro
20120 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 r message explai
20130 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 ning that.** acc
20140 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a ess is denied. .
20150 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
20160 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
20170 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
20180 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 lback is a copy
20190 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 of the third.**
201a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
201b0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
201c0 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 horizer() interf
201d0 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 ace. ^The second
201e0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f parameter.** to
201f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
20200 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c an integer [SQL
20210 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f ITE_COPY | actio
20220 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 n code] that spe
20230 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 cifies.** the pa
20240 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 rticular action
20250 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
20260 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 . ^The third thr
20270 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d ough sixth param
20280 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 eters.** to the
20290 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 callback are zer
202a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
202b0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 ings that contai
202c0 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 n additional.**
202d0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 details about th
202e0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 e action to be a
202f0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a uthorized..**.**
20300 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 ^If the action
20310 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f code is [SQLITE_
20320 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 READ].** and the
20330 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
20340 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 s [SQLITE_IGNORE
20350 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 ] then the.** [p
20360 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
20370 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 t] statement is
20380 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 constructed to s
20390 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e ubstitute.** a N
203a0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 ULL value in pla
203b0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 ce of the table
203c0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c column that woul
203d0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 d have.** been r
203e0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f ead if [SQLITE_O
203f0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 K] had been retu
20400 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 rned. The [SQLI
20410 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 TE_IGNORE].** re
20420 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 turn can be used
20430 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 to deny an untr
20440 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 usted user acces
20450 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a s to individual.
20460 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 ** columns of a
20470 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 table..** ^If th
20480 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 e action code is
20490 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d [SQLITE_DELETE]
204a0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 and the callbac
204b0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 k returns.** [SQ
204c0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 LITE_IGNORE] the
204d0 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f n the [DELETE] o
204e0 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 peration proceed
204f0 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 s but the.** [tr
20500 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 uncate optimizat
20510 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 ion] is disabled
20520 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 and all rows ar
20530 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 e deleted indivi
20540 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e dually..**.** An
20550 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 authorizer is u
20560 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 sed when [sqlite
20570 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
20580 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 aring].** SQL st
20590 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e atements from an
205a0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 untrusted sourc
205b0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 e, to ensure tha
205c0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d t the SQL statem
205d0 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 ents.** do not t
205e0 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 ry to access dat
205f0 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 a they are not a
20600 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f llowed to see, o
20610 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e r that they do n
20620 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 ot.** try to exe
20630 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 cute malicious s
20640 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 tatements that d
20650 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 amage the databa
20660 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d se. For.** exam
20670 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 ple, an applicat
20680 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 ion may allow a
20690 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 user to enter ar
206a0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 bitrary.** SQL q
206b0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 ueries for evalu
206c0 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 ation by a datab
206d0 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 ase. But the ap
206e0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a plication does.*
206f0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 * not want the u
20700 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 ser to be able t
20710 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 o make arbitrary
20720 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a changes to the.
20730 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e ** database. An
20740 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c authorizer coul
20750 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e d then be put in
20760 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 place while the
20770 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 .** user-entered
20780 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 SQL is being [s
20790 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c qlite3_prepare |
207a0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a prepared] that.
207b0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 ** disallows eve
207c0 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b rything except [
207d0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
207e0 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 ts..**.** Applic
207f0 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 ations that need
20800 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 to process SQL
20810 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 from untrusted s
20820 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 ources.** might
20830 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f also consider lo
20840 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 wering resource
20850 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 limits using [sq
20860 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a lite3_limit()].*
20870 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 * and limiting d
20880 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 atabase size usi
20890 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 ng the [max_page
208a0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
208b0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 .** in addition
208c0 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 to using an auth
208d0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 orizer..**.** ^(
208e0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 Only a single au
208f0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 thorizer can be
20900 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 in place on a da
20910 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
20920 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 n.** at a time.
20930 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 Each call to sq
20940 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
20950 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 izer overrides t
20960 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 he.** previous c
20970 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 all.)^ ^Disable
20980 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
20990 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 by installing a
209a0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a NULL callback..*
209b0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
209c0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 is disabled by
209d0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 default..**.** T
209e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
209f0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 llback must not
20a00 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 do anything that
20a10 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 will modify.**
20a20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
20a30 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
20a40 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 oked the authori
20a50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a zer callback..**
20a60 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
20a70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
20a80 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
20a90 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
20aa0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
20ab0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
20ac0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
20ad0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
20ae0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
20af0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c **.** ^When [sql
20b00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
20b10 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 )] is used to pr
20b20 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e epare a statemen
20b30 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d t, the.** statem
20b40 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d ent might be re-
20b50 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 prepared during
20b60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
20b70 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 due to a .** sc
20b80 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 hema change. He
20b90 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 nce, the applica
20ba0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 tion should ensu
20bb0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 re that the.** c
20bc0 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 orrect authorize
20bd0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 r callback remai
20be0 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 ns in place duri
20bf0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ng the [sqlite3_
20c00 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e step()]..**.** ^
20c10 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 Note that the au
20c20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
20c30 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c k is invoked onl
20c40 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c y during.** [sql
20c50 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
20c60 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e or its variants.
20c70 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 Authorization
20c80 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 is not.** perfor
20c90 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 med during state
20ca0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 ment evaluation
20cb0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 in [sqlite3_step
20cc0 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 ()], unless.** a
20cd0 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 s stated in the
20ce0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 previous paragra
20cf0 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 ph, sqlite3_step
20d00 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 () invokes.** sq
20d10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
20d20 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 () to reprepare
20d30 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 a statement afte
20d40 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 r a schema chang
20d50 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
20d60 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 int SQLITE_APIC
20d70 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f ALL sqlite3_set_
20d80 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 authorizer(. sq
20d90 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 53 lite3*,. int (S
20da0 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a QLITE_CALLBACK *
20db0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 xAuth)(void*,int
20dc0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e ,const char*,con
20dd0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 st char*,const c
20de0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
20df0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 ),. void *pUser
20e00 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 Data.);../*.** C
20e10 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 API3REF: Authori
20e20 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 zer Return Codes
20e30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
20e40 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
20e50 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 er | authorizer
20e60 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
20e70 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 n] must.** retur
20e80 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 n either [SQLITE
20e90 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 _OK] or one of t
20ea0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e hese two constan
20eb0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 ts in order.** t
20ec0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 o signal SQLite
20ed0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
20ee0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 he action is per
20ef0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 mitted. See the
20f00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 .** [sqlite3_set
20f10 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 _authorizer | au
20f20 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e thorizer documen
20f30 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 tation] for addi
20f40 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d tional.** inform
20f50 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 ation..**.** Not
20f60 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 e that SQLITE_IG
20f70 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 NORE is also use
20f80 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 d as a [conflict
20f90 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 resolution mode
20fa0 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 ].** returned fr
20fb0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f om the [sqlite3_
20fc0 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 vtab_on_conflict
20fd0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
20fe0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
20ff0 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 _DENY 1 /* A
21000 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 bort the SQL sta
21010 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 tement with an e
21020 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
21030 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 SQLITE_IGNORE 2
21040 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 /* Don't allow
21050 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e access, but don
21060 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 't generate an e
21070 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 rror */../*.** C
21080 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 API3REF: Authori
21090 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 zer Action Codes
210a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
210b0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
210c0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 er()] interface
210d0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c registers a call
210e0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a back function.**
210f0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 that is invoked
21100 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 to authorize ce
21110 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d rtain SQL statem
21120 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 ent actions. Th
21130 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 e.** second para
21140 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c meter to the cal
21150 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 lback is an inte
21160 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 ger code that sp
21170 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 ecifies.** what
21180 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 action is being
21190 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 authorized. The
211a0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 se are the integ
211b0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 er action codes
211c0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 that.** the auth
211d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
211e0 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a may be passed..*
211f0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f *.** These actio
21200 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 n code values si
21210 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 gnify what kind
21220 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 of operation is
21230 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 to be.** authori
21240 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e zed. The 3rd an
21250 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 d 4th parameters
21260 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
21270 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 ation.** callbac
21280 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 k function will
21290 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 be parameters or
212a0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 NULL depending
212b0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 on which of thes
212c0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 e.** codes is us
212d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
212e0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 parameter. ^(T
212f0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
21300 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f to the.** autho
21310 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
21320 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
21330 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 e database ("mai
21340 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 n", "temp",.** e
21350 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 tc.) if applicab
21360 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 le.)^ ^The 6th
21370 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
21380 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
21390 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e back.** is the n
213a0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 ame of the inner
213b0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 -most trigger or
213c0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 view that is re
213d0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a sponsible for.**
213e0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 the access atte
213f0 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 mpt or NULL if t
21400 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d his access attem
21410 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 pt is directly f
21420 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c rom.** top-level
21430 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a SQL code..*/./*
21440 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21450 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21460 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a ********** 3rd *
21470 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 *********** 4th
21480 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 ***********/.#de
21490 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
214a0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 TE_INDEX
214b0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 1 /* Index N
214c0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
214d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
214e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
214f0 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 E_TABLE
21500 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 2 /* Table Na
21510 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
21520 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
21530 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
21540 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 _TEMP_INDEX
21550 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 3 /* Index Nam
21560 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
21570 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
21580 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
21590 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 TEMP_TABLE 4
215a0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
215b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
215c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
215d0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
215e0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 EMP_TRIGGER 5
215f0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
21600 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
21610 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
21620 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
21630 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 MP_VIEW 6
21640 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
21650 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
21660 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
21670 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 QLITE_CREATE_TRI
21680 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 GGER 7
21690 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
216a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
216b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
216c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 LITE_CREATE_VIEW
216d0 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 8 /
216e0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
216f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
21700 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
21710 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 ITE_DELETE
21720 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 9 /*
21730 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
21740 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
21750 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
21760 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 TE_DROP_INDEX
21770 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 10 /*
21780 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
21790 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
217a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
217b0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 E_DROP_TABLE
217c0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 11 /* T
217d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
217e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
217f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
21800 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 _DROP_TEMP_INDEX
21810 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 12 /* In
21820 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
21830 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
21840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21850 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 DROP_TEMP_TABLE
21860 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 13 /* Tab
21870 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
21880 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
21890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
218a0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 ROP_TEMP_TRIGGER
218b0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 14 /* Trig
218c0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
218d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
218e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
218f0 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 OP_TEMP_VIEW
21900 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 15 /* View
21910 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
21920 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
21930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
21940 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 P_TRIGGER
21950 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 16 /* Trigge
21960 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
21970 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
21980 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
21990 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 _VIEW
219a0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 17 /* View Na
219b0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
219c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
219d0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 ine SQLITE_INSER
219e0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
219f0 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 18 /* Table Na
21a00 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
21a10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
21a20 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 ne SQLITE_PRAGMA
21a30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
21a40 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 9 /* Pragma Na
21a50 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f me 1st arg o
21a60 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e r NULL */.#defin
21a70 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 e SQLITE_READ
21a80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20
21a90 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
21aa0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d Column Nam
21ab0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
21ac0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 SQLITE_SELECT
21ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 21
21ae0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
21af0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
21b00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
21b10 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 SQLITE_TRANSACTI
21b20 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 ON 22
21b30 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 /* Operation
21b40 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
21b50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
21b60 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 QLITE_UPDATE
21b70 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 23
21b80 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
21b90 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
21ba0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
21bb0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 LITE_ATTACH
21bc0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 24 /
21bd0 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 * Filename
21be0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
21bf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
21c00 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 ITE_DETACH
21c10 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 25 /*
21c20 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 Database Name
21c30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
21c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
21c50 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 TE_ALTER_TABLE
21c60 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 26 /*
21c70 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 Database Name
21c80 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
21c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
21ca0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 E_REINDEX
21cb0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 27 /* I
21cc0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e ndex Name N
21cd0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
21ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
21cf0 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 _ANALYZE
21d00 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 28 /* Ta
21d10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
21d20 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
21d30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21d40 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 CREATE_VTABLE
21d50 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 29 /* Tab
21d60 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 le Name Mod
21d70 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a ule Name */.
21d80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
21d90 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ROP_VTABLE
21da0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 30 /* Tabl
21db0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 e Name Modu
21dc0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 le Name */.#
21dd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 define SQLITE_FU
21de0 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 NCTION
21df0 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 31 /* NULL
21e00 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 Funct
21e10 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 ion Name */.#d
21e20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 efine SQLITE_SAV
21e30 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 EPOINT
21e40 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 32 /* Operat
21e50 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f ion Savepo
21e60 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 int Name */.#de
21e70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 fine SQLITE_COPY
21e80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
21e90 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 0 /* No long
21ea0 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 er used */.#defi
21eb0 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 ne SQLITE_RECURS
21ec0 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33 IVE 3
21ed0 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 3 /* NULL
21ee0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
21ef0 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a */../*.**
21f00 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 CAPI3REF: Traci
21f10 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 ng And Profiling
21f20 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 Functions.** ME
21f30 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
21f40 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
21f50 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74 65 es are deprecate
21f60 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 d. Use the [sqli
21f70 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 te3_trace_v2()]
21f80 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 interface.** ins
21f90 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 tead of the rout
21fa0 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 68 ines described h
21fb0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ere..**.** These
21fc0 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 routines regist
21fd0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
21fe0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 tions that can b
21ff0 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 e used for.** tr
22000 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c acing and profil
22010 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f ing the executio
22020 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 n of SQL stateme
22030 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
22040 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
22050 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 n registered by
22060 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
22070 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a is invoked at.**
22080 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 various times w
22090 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 hen an SQL state
220a0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 ment is being ru
220b0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 n by [sqlite3_st
220c0 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 ep()]..** ^The s
220d0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 qlite3_trace() c
220e0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
220f0 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 ed with a UTF-8
22100 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
22110 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
22120 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 t text as the st
22130 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 atement first be
22140 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a gins executing..
22150 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 ** ^(Additional
22160 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
22170 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 callbacks might
22180 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 occur.** as each
22190 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 triggered subpr
221a0 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 ogram is entered
221b0 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 . The callbacks
221c0 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a for triggers.**
221d0 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 contain a UTF-8
221e0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 SQL comment tha
221f0 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 t identifies the
22200 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a trigger.)^.**.*
22210 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 * The [SQLITE_TR
22220 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 ACE_SIZE_LIMIT]
22230 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
22240 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
22250 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 to limit.** the
22260 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 length of [bound
22270 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 parameter] expa
22280 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 nsion in the out
22290 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 put of sqlite3_t
222a0 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 race()..**.** ^T
222b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
222c0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
222d0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 by sqlite3_profi
222e0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a le() is invoked.
222f0 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 ** as each SQL s
22300 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 tatement finishe
22310 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 s. ^The profile
22320 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 callback contai
22330 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e ns.** the origin
22340 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 al statement tex
22350 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 t and an estimat
22360 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 e of wall-clock
22370 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c time.** of how l
22380 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 ong that stateme
22390 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 nt took to run.
223a0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 ^The profile ca
223b0 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 llback.** time i
223c0 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 s in units of na
223d0 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 noseconds, howev
223e0 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 er the current i
223f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
22400 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 is only capable
22410 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 of millisecond
22420 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 resolution so th
22430 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e e six least sign
22440 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 ificant.** digit
22450 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 s in the time ar
22460 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 e meaningless.
22470 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
22480 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 of SQLite.** mig
22490 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 ht provide great
224a0 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e er resolution on
224b0 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 the profiler ca
224c0 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 llback. The.**
224d0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
224e0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f ) function is co
224f0 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d nsidered experim
22500 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 ental and is.**
22510 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
22520 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 e in future vers
22530 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ions of SQLite..
22540 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 */.SQLITE_API SQ
22550 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
22560 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 41 50 49 void *SQLITE_API
22570 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61 CALL sqlite3_tra
22580 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 ce(sqlite3*,.
22590 76 6f 69 64 28 53 51 4c 49 54 45 5f 43 41 4c 4c void(SQLITE_CALL
225a0 42 41 43 4b 20 2a 78 54 72 61 63 65 29 28 76 6f BACK *xTrace)(vo
225b0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 id*,const char*)
225c0 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 , void*);.SQLITE
225d0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 _API SQLITE_DEPR
225e0 45 43 41 54 45 44 20 76 6f 69 64 20 2a 53 51 4c ECATED void *SQL
225f0 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 ITE_APICALL sqli
22600 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 te3_profile(sqli
22610 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 53 51 te3*,. void(SQ
22620 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 LITE_CALLBACK *x
22630 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 Profile)(void*,c
22640 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 onst char*,sqlit
22650 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 e3_uint64), void
22660 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
22670 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 REF: SQL Trace E
22680 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 vent Codes.** KE
22690 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 YWORDS: SQLITE_T
226a0 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 RACE.**.** These
226b0 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 constants ident
226c0 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 ify classes of e
226d0 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 vents that can b
226e0 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 e monitored.** u
226f0 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 sing the [sqlite
22700 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 3_trace_v2()] tr
22710 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 acing logic. Th
22720 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
22730 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f .** to [sqlite3_
22740 74 72 61 63 65 5f 76 32 28 29 5d 20 69 73 20 61 trace_v2()] is a
22750 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 n OR-ed combinat
22760 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f ion of one or mo
22770 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c re of.** the fol
22780 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 lowing constants
22790 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 . ^The first ar
227a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 gument to the tr
227b0 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 ace callback.**
227c0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f is one of the fo
227d0 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 llowing constant
227e0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 s..**.** New tra
227f0 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d cing constants m
22800 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
22810 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a uture releases..
22820 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 **.** ^A trace c
22830 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 allback has four
22840 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c arguments: xCal
22850 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a lback(T,C,P,X)..
22860 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 ** ^The T argume
22870 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 nt is one of the
22880 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f integer type co
22890 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 des above..** ^T
228a0 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 he C argument is
228b0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 a copy of the c
228c0 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 ontext pointer p
228d0 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a assed in as the.
228e0 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 ** fourth argume
228f0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 nt to [sqlite3_t
22900 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 race_v2()]..** T
22910 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d he P and X argum
22920 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 ents are pointer
22930 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 s whose meanings
22940 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a depend on T..**
22950 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 .** <dl>.** [[SQ
22960 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d LITE_TRACE_STMT]
22970 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 ] <dt>SQLITE_TRA
22980 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 CE_STMT</dt>.**
22990 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 <dd>^An SQLITE_T
229a0 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 RACE_STMT callba
229b0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 ck is invoked wh
229c0 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74 en a prepared st
229d0 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 atement.** first
229e0 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 begins running
229f0 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 and possibly at
22a00 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 other times duri
22a10 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 ng the.** execut
22a20 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 ion of the prepa
22a30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 red statement, s
22a40 75 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74 uch as at the st
22a50 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 art of each.** t
22a60 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 rigger subprogra
22a70 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 m. ^The P argume
22a80 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 nt is a pointer
22a90 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 to the.** [prepa
22aa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
22ab0 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 ^The X argument
22ac0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
22ad0 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a a string which.*
22ae0 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e * is the unexpan
22af0 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 ded SQL text of
22b00 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 the prepared sta
22b10 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c tement or an SQL
22b20 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 comment .** tha
22b30 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 t indicates the
22b40 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 invocation of a
22b50 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 trigger. ^The c
22b60 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 allback can comp
22b70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 ute.** the same
22b80 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 text that would
22b90 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e have been return
22ba0 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 ed by the legacy
22bb0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 [sqlite3_trace(
22bc0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 )].** interface
22bd0 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 by using the X a
22be0 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 rgument when X b
22bf0 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 egins with "--"
22c00 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 and invoking.**
22c10 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 [sqlite3_expande
22c20 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 d_sql(P)] otherw
22c30 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c ise..**.** [[SQL
22c40 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c ITE_TRACE_PROFIL
22c50 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 E]] <dt>SQLITE_T
22c60 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 RACE_PROFILE</dt
22c70 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c >.** <dd>^An SQL
22c80 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c ITE_TRACE_PROFIL
22c90 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 E callback provi
22ca0 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c des approximatel
22cb0 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e y the same.** in
22cc0 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 formation as is
22cd0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 provided by the
22ce0 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 [sqlite3_profile
22cf0 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ()] callback..**
22d00 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 ^The P argument
22d10 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
22d20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
22d30 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 tatement] and th
22d40 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 e.** X argument
22d50 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 points to a 64-b
22d60 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 it integer which
22d70 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 is the estimate
22d80 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 d of.** the numb
22d90 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 er of nanosecond
22da0 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 that the prepar
22db0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f ed statement too
22dc0 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 k to run..** ^Th
22dd0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 e SQLITE_TRACE_P
22de0 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 ROFILE callback
22df0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 is invoked when
22e00 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 the statement fi
22e10 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b nishes..**.** [[
22e20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 SQLITE_TRACE_ROW
22e30 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 ]] <dt>SQLITE_TR
22e40 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 ACE_ROW</dt>.**
22e50 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 <dd>^An SQLITE_T
22e60 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 RACE_ROW callbac
22e70 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 k is invoked whe
22e80 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64 never a prepared
22e90 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 .** statement ge
22ea0 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 nerates a single
22eb0 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 row of result.
22ec0 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 .** ^The P argu
22ed0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
22ee0 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 r to the [prepar
22ef0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e ed statement] an
22f00 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d d the.** X argum
22f10 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a ent is unused..*
22f20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 *.** [[SQLITE_TR
22f30 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e ACE_CLOSE]] <dt>
22f40 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f SQLITE_TRACE_CLO
22f50 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e SE</dt>.** <dd>^
22f60 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f An SQLITE_TRACE_
22f70 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 CLOSE callback i
22f80 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 s invoked when a
22f90 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
22fa0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a nection closes..
22fb0 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 ** ^The P argume
22fc0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 nt is a pointer
22fd0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 to the [database
22fe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a connection] obj
22ff0 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 ect.** and the X
23000 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 argument is unu
23010 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f sed..** </dl>.*/
23020 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
23030 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 TRACE_STMT
23040 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 0x01.#define SQ
23050 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 LITE_TRACE_PROFI
23060 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 LE 0x02.#defi
23070 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f ne SQLITE_TRACE_
23080 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a ROW 0x04.
23090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
230a0 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 RACE_CLOSE
230b0 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 0x08../*.** CAPI
230c0 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 3REF: SQL Trace
230d0 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 Hook.** METHOD:
230e0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
230f0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 he sqlite3_trace
23100 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 _v2(D,M,X,P) int
23110 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
23120 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 a trace callbac
23130 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 k.** function X
23140 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 against [databas
23150 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c e connection] D,
23160 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 using property
23170 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f mask M.** and co
23180 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e ntext pointer P.
23190 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c ^If the X call
231a0 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 back is.** NULL
231b0 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b or if the M mask
231c0 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 is zero, then t
231d0 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c racing is disabl
231e0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 ed. The.** M ar
231f0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 gument should be
23200 20 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d the bitwise OR-
23210 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f ed combination o
23220 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 f.** zero or mor
23230 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d e [SQLITE_TRACE]
23240 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a constants..**.*
23250 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 * ^Each call to
23260 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 either sqlite3_t
23270 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 race() or sqlite
23280 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 3_trace_v2() ove
23290 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 rrides .** (canc
232a0 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 els) any prior c
232b0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
232c0 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 trace() or sqlit
232d0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a e3_trace_v2()..*
232e0 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c *.** ^The X call
232f0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
23300 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 whenever any of
23310 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 the events ident
23320 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 ified by .** mas
23330 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 k M occur. ^The
23340 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 integer return
23350 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 value from the c
23360 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 allback is curre
23370 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c ntly.** ignored,
23380 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 though this may
23390 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 change in futur
233a0 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c e releases. Cal
233b0 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 lback.** impleme
233c0 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ntations should
233d0 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 return zero to e
233e0 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d nsure future com
233f0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a patibility..**.*
23400 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 * ^A trace callb
23410 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
23420 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e ith four argumen
23430 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 ts: callback(T,C
23440 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 ,P,X)..** ^The T
23450 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 argument is one
23460 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f of the [SQLITE_
23470 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 TRACE].** consta
23480 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 nts to indicate
23490 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b why the callback
234a0 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a was invoked..**
234b0 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 ^The C argument
234c0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
234d0 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 e context pointe
234e0 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 r..** The P and
234f0 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 X arguments are
23500 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d pointers whose m
23510 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f eanings depend o
23520 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 n T..**.** The s
23530 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 qlite3_trace_v2(
23540 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 ) interface is i
23550 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 ntended to repla
23560 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a ce the legacy.**
23570 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c interfaces [sql
23580 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e ite3_trace()] an
23590 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 d [sqlite3_profi
235a0 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 le()], both of w
235b0 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 hich.** are depr
235c0 65 63 61 74 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 ecated..*/.SQLIT
235d0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
235e0 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 _APICALL sqlite3
235f0 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c _trace_v2(. sql
23600 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 ite3*,. unsigne
23610 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 53 d uMask,. int(S
23620 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a QLITE_CALLBACK *
23630 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 xCallback)(unsig
23640 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c ned,void*,void*,
23650 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a void*),. void *
23660 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pCtx.);../*.** C
23670 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 API3REF: Query P
23680 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b rogress Callback
23690 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
236a0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ite3.**.** ^The
236b0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 sqlite3_progress
236c0 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 _handler(D,N,X,P
236d0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 ) interface caus
236e0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a es the callback.
236f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f ** function X to
23700 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 be invoked peri
23710 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 odically during
23720 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c long running cal
23730 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ls to.** [sqlite
23740 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 3_exec()], [sqli
23750 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 te3_step()] and
23760 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
23770 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 le()] for.** dat
23780 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
23790 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 D. An example
237a0 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 use for this.**
237b0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 interface is to
237c0 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 keep a GUI updat
237d0 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 ed during a larg
237e0 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e e query..**.** ^
237f0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 The parameter P
23800 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 is passed throug
23810 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 h as the only pa
23820 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a rameter to the .
23830 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 ** callback func
23840 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 tion X. ^The pa
23850 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 rameter N is the
23860 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d approximate num
23870 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 ber of .** [virt
23880 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 ual machine inst
23890 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 ructions] that a
238a0 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 re evaluated bet
238b0 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a ween successive.
238c0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f ** invocations o
238d0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 f the callback X
238e0 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 . ^If N is less
238f0 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 than one then t
23900 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 he progress.** h
23910 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c andler is disabl
23920 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 ed..**.** ^Only
23930 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 a single progres
23940 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 s handler may be
23950 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 defined at one
23960 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 time per.** [dat
23970 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
23980 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 ]; setting a new
23990 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
239a0 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a r cancels the.**
239b0 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 old one. ^Sett
239c0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 ing parameter X
239d0 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 to NULL disables
239e0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 the progress ha
239f0 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 ndler..** ^The p
23a00 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 rogress handler
23a10 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 is also disabled
23a20 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f by setting N to
23a30 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a a value less.**
23a40 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e than 1..**.** ^
23a50 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 If the progress
23a60 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
23a70 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f non-zero, the o
23a80 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 peration is.** i
23a90 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 nterrupted. Thi
23aa0 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 s feature can be
23ab0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 used to impleme
23ac0 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 nt a.** "Cancel"
23ad0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 button on a GUI
23ae0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 progress dialog
23af0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 box..**.** The
23b00 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
23b10 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e callback must n
23b20 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 ot do anything t
23b30 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a hat will modify.
23b40 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
23b50 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
23b60 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 invoked the prog
23b70 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a ress handler..**
23b80 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
23b90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
23ba0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
23bb0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
23bc0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
23bd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
23be0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
23bf0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
23c00 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
23c10 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 **.*/.SQLITE_API
23c20 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 41 50 49 void SQLITE_API
23c30 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f CALL sqlite3_pro
23c40 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 gress_handler(sq
23c50 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 lite3*, int, int
23c60 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b (SQLITE_CALLBACK
23c70 20 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 *)(void*), void
23c80 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
23c90 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e REF: Opening A N
23ca0 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e ew Database Conn
23cb0 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 ection.** CONSTR
23cc0 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a UCTOR: sqlite3.*
23cd0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
23ce0 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c ines open an SQL
23cf0 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c ite database fil
23d00 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 e as specified b
23d10 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 y the .** filena
23d20 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 me argument. ^Th
23d30 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d e filename argum
23d40 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 ent is interpret
23d50 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a ed as UTF-8 for.
23d60 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ** sqlite3_open(
23d70 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
23d80 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 en_v2() and as U
23d90 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 TF-16 in the nat
23da0 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 ive byte.** orde
23db0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 r for sqlite3_op
23dc0 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 en16(). ^(A [dat
23dd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
23de0 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 ] handle is usua
23df0 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lly.** returned
23e00 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 in *ppDb, even i
23e10 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
23e20 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 s. The only exc
23e30 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a eption is that.*
23e40 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 * if SQLite is u
23e50 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
23e60 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 e memory to hold
23e70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
23e80 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c bject,.** a NULL
23e90 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e will be written
23ea0 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 into *ppDb inst
23eb0 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 ead of a pointer
23ec0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
23ed0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e ].** object.)^ ^
23ee0 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 (If the database
23ef0 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f is opened (and/
23f00 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 or created) succ
23f10 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a essfully, then.*
23f20 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 * [SQLITE_OK] is
23f30 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 returned. Othe
23f40 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 rwise an [error
23f50 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
23f60 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 d.)^ ^The.** [sq
23f70 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 lite3_errmsg()]
23f80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d or [sqlite3_errm
23f90 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 sg16()] routines
23fa0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
23fb0 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 obtain.** an Eng
23fc0 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 lish language de
23fd0 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 scription of the
23fe0 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 error following
23ff0 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e a failure of an
24000 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 y.** of the sqli
24010 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 te3_open() routi
24020 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nes..**.** ^The
24030 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 default encoding
24040 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 will be UTF-8 f
24050 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65 or databases cre
24060 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 ated using.** sq
24070 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
24080 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
24090 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 ). ^The default
240a0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 encoding for da
240b0 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 tabases.** creat
240c0 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 ed using sqlite3
240d0 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 _open16() will b
240e0 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 e UTF-16 in the
240f0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
24100 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 r..**.** Whether
24110 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 or not an error
24120 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 occurs when it
24130 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 is opened, resou
24140 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 rces.** associat
24150 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 ed with the [dat
24160 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
24170 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 ] handle should
24180 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a be released by.*
24190 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 * passing it to
241a0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
241b0 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 ] when it is no
241c0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e longer required.
241d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
241e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 e3_open_v2() int
241f0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b erface works lik
24200 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 e sqlite3_open()
24210 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 .** except that
24220 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 it accepts two a
24230 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 dditional parame
24240 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f ters for additio
24250 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f nal control.** o
24260 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 ver the new data
24270 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
24280 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 ^(The flags pa
24290 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 rameter to.** sq
242a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
242b0 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a can take one of.
242c0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ** the following
242d0 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f three values, o
242e0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e ptionally combin
242f0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 ed with the .**
24300 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d [SQLITE_OPEN_NOM
24310 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f UTEX], [SQLITE_O
24320 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 PEN_FULLMUTEX],
24330 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 [SQLITE_OPEN_SHA
24340 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 REDCACHE],.** [S
24350 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
24360 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 TECACHE], and/or
24370 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 [SQLITE_OPEN_UR
24380 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a I] flags:)^.**.*
24390 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e * <dl>.** ^(<dt>
243a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
243b0 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c DONLY]</dt>.** <
243c0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
243d0 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 is opened in rea
243e0 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 d-only mode. If
243f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f the database do
24400 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 es not.** alread
24410 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f y exist, an erro
24420 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f r is returned.</
24430 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 dd>)^.**.** ^(<d
24440 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 t>[SQLITE_OPEN_R
24450 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a EADWRITE]</dt>.*
24460 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
24470 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
24480 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 reading and wri
24490 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 ting if possible
244a0 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 , or reading.**
244b0 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 only if the file
244c0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 is write protec
244d0 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 ted by the opera
244e0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e ting system. In
244f0 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 either.** case
24500 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 the database mus
24510 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c t already exist,
24520 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 otherwise an er
24530 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ror is returned.
24540 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 </dd>)^.**.** ^(
24550 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e <dt>[SQLITE_OPEN
24560 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 _READWRITE] | [S
24570 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
24580 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 E]</dt>.** <dd>T
24590 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
245a0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e pened for readin
245b0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 g and writing, a
245c0 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 nd is created if
245d0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 .** it does not
245e0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 already exist. T
245f0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 his is the behav
24600 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 ior that is alwa
24610 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 ys used for.** s
24620 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
24630 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 d sqlite3_open16
24640 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f ().</dd>)^.** </
24650 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 dl>.**.** If the
24660 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
24670 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
24680 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 2() is not one o
24690 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 f the.** combina
246a0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 tions shown abov
246b0 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d e optionally com
246c0 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 bined with other
246d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
246e0 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 _READONLY | SQLI
246f0 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a TE_OPEN_* bits].
24700 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 ** then the beha
24710 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
24720 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 d..**.** ^If the
24730 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
24740 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 MUTEX] flag is s
24750 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 et, then the dat
24760 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
24770 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 .** opens in the
24780 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 multi-thread [t
24790 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 hreading mode] a
247a0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 s long as the si
247b0 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d ngle-thread.** m
247c0 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e ode has not been
247d0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d set at compile-
247e0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 time or start-ti
247f0 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 me. ^If the.**
24800 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c [SQLITE_OPEN_FUL
24810 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 LMUTEX] flag is
24820 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 set then the dat
24830 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
24840 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 opens.** in the
24850 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 serialized [thr
24860 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c eading mode] unl
24870 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 ess single-threa
24880 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 d was.** previou
24890 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 sly selected at
248a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 compile-time or
248b0 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e start-time..** ^
248c0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
248d0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c _SHAREDCACHE] fl
248e0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 ag causes the da
248f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
24900 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 n to be.** eligi
24910 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 ble to use [shar
24920 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 ed cache mode],
24930 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 regardless of wh
24940 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 ether or not sha
24950 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 red.** cache is
24960 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 enabled using [s
24970 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 qlite3_enable_sh
24980 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 ared_cache()].
24990 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ^The.** [SQLITE_
249a0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
249b0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 E] flag causes t
249c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
249d0 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a ection to not.**
249e0 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 participate in
249f0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f [shared cache mo
24a00 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 de] even if it i
24a10 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a s enabled..**.**
24a20 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 ^The fourth par
24a30 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
24a40 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 3_open_v2() is t
24a50 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a he name of the.*
24a60 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 * [sqlite3_vfs]
24a70 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 object that defi
24a80 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e nes the operatin
24a90 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 g system interfa
24aa0 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e ce that.** the n
24ab0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
24ac0 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 ection should us
24ad0 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 e. ^If the four
24ae0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a th parameter is.
24af0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ** a NULL pointe
24b00 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 r then the defau
24b10 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
24b20 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e object is used.
24b30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .**.** ^If the f
24b40 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d ilename is ":mem
24b50 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 ory:", then a pr
24b60 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 ivate, temporary
24b70 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
24b80 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 ase.** is create
24b90 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 d for the connec
24ba0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d tion. ^This in-
24bb0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 memory database
24bc0 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e will vanish when
24bd0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
24be0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
24bf0 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 losed. Future v
24c00 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
24c10 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 e might.** make
24c20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 use of additiona
24c30 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 l special filena
24c40 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 mes that begin w
24c50 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 ith the ":" char
24c60 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 acter..** It is
24c70 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 recommended that
24c80 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 when a database
24c90 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c filename actual
24ca0 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 ly does begin wi
24cb0 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 th.** a ":" char
24cc0 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 acter you should
24cd0 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 prefix the file
24ce0 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 name with a path
24cf0 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 name such as.**
24d00 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d "./" to avoid am
24d10 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e biguity..**.** ^
24d20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 If the filename
24d30 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 is an empty stri
24d40 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 ng, then a priva
24d50 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a te, temporary.**
24d60 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 on-disk databas
24d70 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 e will be create
24d80 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 d. ^This privat
24d90 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 e database will
24da0 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 be.** automatica
24db0 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 lly deleted as s
24dc0 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 oon as the datab
24dd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
24de0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 s closed..**.**
24df0 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 [[URI filenames
24e00 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 in sqlite3_open(
24e10 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 )]] <h3>URI File
24e20 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a names</h3>.**.**
24e30 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 ^If [URI filena
24e40 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 me] interpretati
24e50 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 on is enabled, a
24e60 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 nd the filename
24e70 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 argument.** begi
24e80 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c ns with "file:",
24e90 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 then the filena
24ea0 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 me is interprete
24eb0 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 d as a URI. ^URI
24ec0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 .** filename int
24ed0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 erpretation is e
24ee0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 nabled if the [S
24ef0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 QLITE_OPEN_URI]
24f00 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 flag is.** set i
24f10 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 n the fourth arg
24f20 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
24f30 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 _open_v2(), or i
24f40 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e f it has.** been
24f50 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c enabled globall
24f60 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c y using the [SQL
24f70 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 ITE_CONFIG_URI]
24f80 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a option with the.
24f90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
24fa0 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 ig()] method or
24fb0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 by the [SQLITE_U
24fc0 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d SE_URI] compile-
24fd0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 time option..**
24fe0 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 As of SQLite ver
24ff0 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 sion 3.7.7, URI
25000 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 filename interpr
25010 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 etation is turne
25020 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 d off.** by defa
25030 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 ult, but future
25040 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
25050 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 te might enable
25060 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 URI filename.**
25070 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 interpretation b
25080 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 y default. See
25090 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d "[URI filenames]
250a0 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c " for additional
250b0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e .** information.
250c0 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e .**.** URI filen
250d0 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 ames are parsed
250e0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 according to RFC
250f0 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 3986. ^If the U
25100 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a RI contains an.*
25110 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 * authority, the
25120 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 n it must be eit
25130 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 her an empty str
25140 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e ing or the strin
25150 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 g .** "localhost
25160 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f ". ^If the autho
25170 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 rity is not an e
25180 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 mpty string or "
25190 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a localhost", an .
251a0 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 ** error is retu
251b0 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c rned to the call
251c0 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e er. ^The fragmen
251d0 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 t component of a
251e0 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 URI, if .** pre
251f0 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 sent, is ignored
25200 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ..**.** ^SQLite
25210 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f uses the path co
25220 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 mponent of the U
25230 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f RI as the name o
25240 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a f the disk file.
25250 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e ** which contain
25260 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 s the database.
25270 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 ^If the path beg
25280 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 ins with a '/' c
25290 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 haracter, .** th
252a0 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 en it is interpr
252b0 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c eted as an absol
252c0 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 ute path. ^If th
252d0 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 e path does not
252e0 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 begin .** with a
252f0 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 '/' (meaning th
25300 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 at the authority
25310 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 section is omit
25320 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 ted from the URI
25330 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 ).** then the pa
25340 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 th is interprete
25350 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 d as a relative
25360 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 path. .** ^(On w
25370 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 indows, the firs
25380 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 t component of a
25390 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 n absolute path
253a0 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 .** is a drive s
253b0 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e pecification (e.
253c0 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a g. "C:").)^.**.*
253d0 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 * [[core URI que
253e0 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a ry parameters]].
253f0 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d ** The query com
25400 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 ponent of a URI
25410 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 may contain para
25420 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 meters that are
25430 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 interpreted.** e
25440 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 ither by SQLite
25450 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 itself, or by a
25460 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 [VFS | custom VF
25470 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
25480 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 ]..** SQLite and
25490 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 its built-in [V
254a0 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 FSes] interpret
254b0 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 the.** following
254c0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
254d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
254e0 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f <li> <b>vfs</
254f0 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 b>: ^The "vfs" p
25500 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 arameter may be
25510 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 used to specify
25520 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 the name of.**
25530 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 a VFS object
25540 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 that provides th
25550 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
25560 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 em interface tha
25570 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 t should.**
25580 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 be used to acces
25590 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 s the database f
255a0 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 ile on disk. ^If
255b0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 this option is
255c0 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e set to.** an
255d0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 empty string th
255e0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 e default VFS ob
255f0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 ject is used. ^S
25600 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b pecifying an unk
25610 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 nown.** VFS
25620 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 is an error. ^If
25630 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
25640 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 () is used and t
25650 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 he vfs option is
25660 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c .** present,
25670 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 then the VFS sp
25680 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f ecified by the o
25690 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 ption takes prec
256a0 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 edence over.**
256b0 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 the value pas
256c0 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 sed as the fourt
256d0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
256e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
256f0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c ..**.** <li> <
25700 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 b>mode</b>: ^(Th
25710 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 e mode parameter
25720 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 may be set to e
25730 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 ither "ro", "rw"
25740 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 ,.** "rwc",
25750 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 or "memory". Att
25760 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 empting to set i
25770 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 t to any other v
25780 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 alue is.** a
25790 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 n error)^. .**
257a0 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 ^If "ro" is s
257b0 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 pecified, then t
257c0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
257d0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f pened for read-o
257e0 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 nly .** acce
257f0 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 ss, just as if t
25800 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
25810 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 READONLY] flag h
25820 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 ad been set in t
25830 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 he .** third
25840 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
25850 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 ite3_open_v2().
25860 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 ^If the mode opt
25870 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a ion is set to .*
25880 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e * "rw", then
25890 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
258a0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
258b0 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 -write (but not
258c0 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 create) .**
258d0 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 access, as if SQ
258e0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
258f0 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c ITE (but not SQL
25900 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 ITE_OPEN_CREATE)
25910 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 had .** bee
25920 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 n set. ^Value "r
25930 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e wc" is equivalen
25940 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 t to setting bot
25950 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 h .** SQLITE
25960 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 _OPEN_READWRITE
25970 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f and SQLITE_OPEN_
25980 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 CREATE. ^If the
25990 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a mode option is.
259a0 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d ** set to "m
259b0 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 emory" then a pu
259c0 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 re [in-memory da
259d0 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 tabase] that nev
259e0 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 er reads.**
259f0 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 or writes from d
25a00 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 isk is used. ^It
25a10 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 is an error to
25a20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 specify a value
25a30 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d for.** the m
25a40 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 ode parameter th
25a50 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 at is less restr
25a60 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 ictive than that
25a70 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a specified by.**
25a80 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 the flags p
25a90 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 assed in the thi
25aa0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
25ab0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
25ac0 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 )..**.** <li>
25ad0 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 <b>cache</b>: ^T
25ae0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 he cache paramet
25af0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f er may be set to
25b00 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 either "shared"
25b10 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 or.** "priv
25b20 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 ate". ^Setting i
25b30 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 t to "shared" is
25b40 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 equivalent to s
25b50 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 etting the.**
25b60 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 SQLITE_OPEN_SH
25b70 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e AREDCACHE bit in
25b80 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d the flags argum
25b90 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a ent passed to.**
25ba0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 sqlite3_ope
25bb0 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 n_v2(). ^Setting
25bc0 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d the cache param
25bd0 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 eter to "private
25be0 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 " is .** equ
25bf0 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 ivalent to setti
25c00 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 ng the SQLITE_OP
25c10 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 EN_PRIVATECACHE
25c20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 bit..** ^If
25c30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
25c40 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 ) is used and th
25c50 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 e "cache" parame
25c60 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 ter is present i
25c70 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 n.** a URI f
25c80 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c ilename, its val
25c90 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 ue overrides any
25ca0 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 behavior reques
25cb0 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a ted by setting.*
25cc0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 * SQLITE_OPE
25cd0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f N_PRIVATECACHE o
25ce0 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 r SQLITE_OPEN_SH
25cf0 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a AREDCACHE flag..
25d00 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 **.** <li> <b>p
25d10 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 sow</b>: ^The ps
25d20 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 ow parameter ind
25d30 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f icates whether o
25d40 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 r not the.**
25d50 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 [powersafe over
25d60 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 write] property
25d70 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 does or does not
25d80 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a apply to the.**
25d90 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 storage med
25da0 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 ia on which the
25db0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 database file re
25dc0 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c sides..**.** <l
25dd0 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e i> <b>nolock</b>
25de0 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 : ^The nolock pa
25df0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f rameter is a boo
25e00 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d lean query param
25e10 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 eter.** whic
25e20 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 h if set disable
25e30 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 s file locking i
25e40 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e n rollback journ
25e50 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a al modes. This.
25e60 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c ** is useful
25e70 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 for accessing a
25e80 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 database on a f
25e90 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 ilesystem that d
25ea0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 oes not.** s
25eb0 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 upport locking.
25ec0 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 Caution: Datab
25ed0 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d ase corruption m
25ee0 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 ight result if t
25ef0 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 wo.** or mor
25f00 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 e processes writ
25f10 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 e to the same da
25f20 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f tabase and any o
25f30 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 ne of those.**
25f40 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 processes use
25f50 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a s nolock=1..**.*
25f60 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 * <li> <b>immut
25f70 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 able</b>: ^The i
25f80 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 mmutable paramet
25f90 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 er is a boolean
25fa0 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 query.** par
25fb0 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 ameter that indi
25fc0 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64 cates that the d
25fd0 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 atabase file is
25fe0 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 stored on.**
25ff0 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 read-only media
26000 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 . ^When immutab
26010 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 le is set, SQLit
26020 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 e assumes that t
26030 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 he.** databa
26040 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 se file cannot b
26050 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 e changed, even
26060 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 by a process wit
26070 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 h higher.**
26080 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 privilege, and s
26090 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 o the database i
260a0 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e s opened read-on
260b0 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 ly and all locki
260c0 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 ng.** and ch
260d0 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 ange detection i
260e0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 s disabled. Cau
260f0 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 tion: Setting th
26100 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 e immutable.**
26110 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 property on a
26120 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 database file t
26130 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 hat does in fact
26140 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 change can resu
26150 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 lt.** in inc
26160 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73 orrect query res
26170 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c ults and/or [SQL
26180 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 ITE_CORRUPT] err
26190 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 ors..** See
261a0 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f also: [SQLITE_IO
261b0 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a CAP_IMMUTABLE]..
261c0 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 ** .** </u
261d0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 l>.**.** ^Specif
261e0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 ying an unknown
261f0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 parameter in the
26200 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
26210 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 of a URI is not
26220 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 an.** error. F
26230 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
26240 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 f SQLite might u
26250 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 nderstand additi
26260 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 onal query.** pa
26270 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 rameters. See "
26280 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 [query parameter
26290 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d s with special m
262a0 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 eaning to SQLite
262b0 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 ]" for.** additi
262c0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
262d0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 ..**.** [[URI fi
262e0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d lename examples]
262f0 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 ] <h3>URI filena
26300 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e me examples</h3>
26310 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f .**.** <table bo
26320 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 rder="1" align=c
26330 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e enter cellpaddin
26340 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e g=5>.** <tr><th>
26350 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c URI filenames <
26360 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c th> Results.** <
26370 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 tr><td> file:dat
26380 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 a.db <td> .**
26390 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 Open the
263a0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 file "data.db" i
263b0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 n the current di
263c0 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e rectory..** <tr>
263d0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f <td> file:/home/
263e0 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e fred/data.db<br>
263f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c .** fil
26400 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 e:///home/fred/d
26410 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 ata.db <br> .**
26420 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f file://
26430 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 localhost/home/f
26440 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e red/data.db <br>
26450 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
26460 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 Open the data
26470 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 base file "/home
26480 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a /fred/data.db"..
26490 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
264a0 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 ://darkstar/home
264b0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 /fred/data.db <t
264c0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
264d0 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 An error. "darks
264e0 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 tar" is not a re
264f0 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 cognized authori
26500 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 ty..** <tr><td s
26510 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 tyle="white-spac
26520 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 e:nowrap"> .**
26530 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f file:///
26540 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 C:/Documents%20a
26550 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 nd%20Settings/fr
26560 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e ed/Desktop/data.
26570 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 db.** <td> W
26580 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 indows only: Ope
26590 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 n the file "data
265a0 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 .db" on fred's d
265b0 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a esktop on drive.
265c0 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 ** C:.
265d0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 Note that the %2
265e0 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 0 escaping in th
265f0 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f is example is no
26600 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 t strictly .**
26610 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 necessar
26620 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 y - space charac
26630 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 ters can be used
26640 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 literally.**
26650 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 in URI fi
26660 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e lenames..** <tr>
26670 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 <td> file:data.d
26680 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d b?mode=ro&cache=
26690 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a private <td> .**
266a0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 Open f
266b0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e ile "data.db" in
266c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 the current dir
266d0 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d ectory for read-
266e0 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 only access..**
266f0 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c Regardl
26700 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
26710 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 r not shared-cac
26720 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c he mode is enabl
26730 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 ed by.**
26740 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 default, use a
26750 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a private cache..
26760 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
26770 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 :/home/fred/data
26780 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 .db?vfs=unix-dot
26790 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 file <td>.**
267a0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 Open file
267b0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 "/home/fred/data
267c0 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 .db". Use the sp
267d0 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d ecial VFS "unix-
267e0 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 dotfile".**
267f0 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64 that uses d
26800 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 ot-files in plac
26810 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 e of posix advis
26820 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 ory locking..**
26830 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 <tr><td> file:da
26840 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f ta.db?mode=reado
26850 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 nly <td> .**
26860 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 An error.
26870 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f "readonly" is no
26880 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e t a valid option
26890 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 for the "mode"
268a0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f parameter..** </
268b0 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 table>.**.** ^UR
268c0 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 I hexadecimal es
268d0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 cape sequences (
268e0 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 %HH) are support
268f0 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 ed within the pa
26900 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 th and.** query
26910 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 components of a
26920 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d URI. A hexadecim
26930 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e al escape sequen
26940 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 ce consists of a
26950 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e .** percent sign
26960 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 - "%" - followe
26970 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f d by exactly two
26980 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 hexadecimal dig
26990 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 its .** specifyi
269a0 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 ng an octet valu
269b0 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 e. ^Before the p
269c0 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d ath or query com
269d0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 ponents of a.**
269e0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 URI filename are
269f0 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 interpreted, th
26a00 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 ey are encoded u
26a10 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 sing UTF-8 and a
26a20 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d ll .** hexadecim
26a30 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e al escape sequen
26a40 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 ces replaced by
26a50 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f a single byte co
26a60 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 ntaining the.**
26a70 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 corresponding oc
26a80 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f tet. If this pro
26a90 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 cess generates a
26aa0 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 n invalid UTF-8
26ab0 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 encoding,.** the
26ac0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
26ad0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 efined..**.** <b
26ae0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 >Note to Windows
26af0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 users:</b> The
26b00 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 encoding used f
26b10 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 or the filename
26b20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 argument.** of s
26b30 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
26b40 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 d sqlite3_open_v
26b50 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 2() must be UTF-
26b60 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 8, not whatever.
26b70 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 ** codepage is c
26b80 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
26b90 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e . Filenames con
26ba0 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 taining internat
26bb0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 ional.** charact
26bc0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ers must be conv
26bd0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 erted to UTF-8 p
26be0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 rior to passing
26bf0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c them into.** sql
26c00 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 ite3_open() or s
26c10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
26c20 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 ..**.** <b>Note
26c30 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 to Windows Runti
26c40 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 me users:</b> T
26c50 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 he temporary dir
26c60 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 ectory must be s
26c70 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 et.** prior to c
26c80 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f alling sqlite3_o
26c90 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
26ca0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 _open_v2(). Oth
26cb0 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a erwise, various.
26cc0 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 ** features that
26cd0 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 require the use
26ce0 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 of temporary fi
26cf0 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a les may fail..**
26d00 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
26d10 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 qlite3_temp_dire
26d20 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 ctory].*/.SQLITE
26d30 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
26d40 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f APICALL sqlite3_
26d50 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 open(. const ch
26d60 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 ar *filename,
26d70 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
26d80 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a name (UTF-8) */.
26d90 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
26da0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
26db0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
26dc0 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f le */.);.SQLITE_
26dd0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 API int SQLITE_A
26de0 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f PICALL sqlite3_o
26df0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 pen16(. const v
26e00 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 oid *filename,
26e10 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
26e20 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a ename (UTF-16) *
26e30 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
26e40 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db /* O
26e50 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
26e60 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 ndle */.);.SQLIT
26e70 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
26e80 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 _APICALL sqlite3
26e90 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 _open_v2(. cons
26ea0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
26eb0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
26ec0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
26ed0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
26ee0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a ppDb, /*
26ef0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
26f00 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 handle */. int
26f10 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 flags,
26f20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a /* Flags */.
26f30 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 const char *zV
26f40 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d fs /* Nam
26f50 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 e of VFS module
26f60 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a to use */.);../*
26f70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
26f80 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 tain Values For
26f90 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a URI Parameters.*
26fa0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 *.** These are u
26fb0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c tility routines,
26fc0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 useful to VFS i
26fd0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 mplementations,
26fe0 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f that check.** to
26ff0 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 see if a databa
27000 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 se file was a UR
27010 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 I that contained
27020 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 a specific quer
27030 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c y .** parameter,
27040 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 and if so obtai
27050 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ns the value of
27060 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d that query param
27070 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 eter..**.** If F
27080 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 is the database
27090 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 filename pointe
270a0 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 r passed into th
270b0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 e xOpen() method
270c0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d of .** a VFS im
270d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 plementation whe
270e0 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 n the flags para
270f0 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 meter to xOpen()
27100 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 has one or .**
27110 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c more of the [SQL
27120 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 ITE_OPEN_URI] or
27130 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
27140 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 IN_DB] bits set
27150 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 and.** P is the
27160 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 name of the quer
27170 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 y parameter, the
27180 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 n.** sqlite3_uri
27190 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 _parameter(F,P)
271a0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 returns the valu
271b0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 e of the P.** pa
271c0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 rameter if it ex
271d0 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 ists or a NULL p
271e0 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 ointer if P does
271f0 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 not appear as a
27200 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d .** query param
27210 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 eter on F. If P
27220 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 is a query para
27230 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 meter of F.** ha
27240 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 s no explicit va
27250 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 lue, then sqlite
27260 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
27270 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 F,P) returns.**
27280 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
27290 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a empty string..**
272a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
272b0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
272c0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d B) routine assum
272d0 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 es that P is a b
272e0 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 oolean.** parame
272f0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ter and returns
27300 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 true (1) or fals
27310 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 e (0) according
27320 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 to the value.**
27330 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 of P. The sqlit
27340 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
27350 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 ,P,B) routine re
27360 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 turns true (1) i
27370 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f f the.** value o
27380 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 f query paramete
27390 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 r P is one of "y
273a0 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 es", "true", or
273b0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 "on" in any.** c
273c0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 ase or if the va
273d0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 lue begins with
273e0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 a non-zero numbe
273f0 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 r. The .** sqli
27400 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
27410 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 F,P,B) routines
27420 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 returns false (0
27430 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f ) if the value o
27440 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d f.** query param
27450 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 eter P is one of
27460 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 "no", "false",
27470 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 or "off" in any
27480 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 case or.** if th
27490 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 e value begins w
274a0 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 ith a numeric ze
274b0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 ro. If P is not
274c0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 a query.** para
274d0 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 meter on F or if
274e0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
274f0 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 is does not matc
27500 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 h any of the.**
27510 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 above, then sqli
27520 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
27530 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 F,P,B) returns (
27540 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 B!=0)..**.** The
27550 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 sqlite3_uri_int
27560 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 64(F,P,D) routin
27570 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 e converts the v
27580 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 alue of P into a
27590 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 .** 64-bit signe
275a0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 d integer and re
275b0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 turns that integ
275c0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f er, or D if P do
275d0 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e es not.** exist.
275e0 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f If the value o
275f0 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 f P is something
27600 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 other than an i
27610 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 nteger, then.**
27620 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 zero is returned
27630 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 ..** .** If F is
27640 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
27650 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
27660 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 i_parameter(F,P)
27670 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e returns NULL an
27680 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 d.** sqlite3_uri
27690 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
276a0 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 returns B. If F
276b0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 is not a NULL p
276c0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 ointer and.** is
276d0 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 not a database
276e0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f file pathname po
276f0 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 inter that SQLit
27700 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 e passed into th
27710 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d e xOpen.** VFS m
27720 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 ethod, then the
27730 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 behavior of this
27740 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 routine is unde
27750 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
27760 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c ly.** undesirabl
27770 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
27780 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
27790 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 ITE_APICALL sqli
277a0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 te3_uri_paramete
277b0 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 r(const char *zF
277c0 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 ilename, const c
277d0 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 har *zParam);.SQ
277e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
277f0 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 ITE_APICALL sqli
27800 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
27810 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c const char *zFil
27820 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a e, const char *z
27830 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 Param, int bDefa
27840 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ult);.SQLITE_API
27850 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 sqlite3_int64 S
27860 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 QLITE_APICALL sq
27870 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 lite3_uri_int64(
27880 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e const char*, con
27890 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 st char*, sqlite
278a0 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 3_int64);.../*.*
278b0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f * CAPI3REF: Erro
278c0 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 r Codes And Mess
278d0 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ages.** METHOD:
278e0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 sqlite3.**.** ^I
278f0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
27900 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 t sqlite3_* API
27910 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 call associated
27920 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 with .** [databa
27930 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
27940 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 failed, then th
27950 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 e sqlite3_errcod
27960 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a e(D) interface.*
27970 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 * returns the nu
27980 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f meric [result co
27990 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 de] or [extended
279a0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f result code] fo
279b0 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 r that.** API ca
279c0 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f ll..** If the mo
279d0 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 st recent API ca
279e0 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75 ll was successfu
279f0 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 l,.** then the r
27a00 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d eturn value from
27a10 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
27a20 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e () is undefined.
27a30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
27a40 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 _extended_errcod
27a50 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 e().** interface
27a60 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 is the same exc
27a70 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 ept that it alwa
27a80 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a ys returns the .
27a90 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
27aa0 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 ult code] even w
27ab0 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 hen extended res
27ac0 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a ult codes are.**
27ad0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a disabled..**.**
27ae0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 ^The sqlite3_er
27af0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 rmsg() and sqlit
27b00 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 e3_errmsg16() re
27b10 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e turn English-lan
27b20 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 guage.** text th
27b30 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 at describes the
27b40 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 error, as eithe
27b50 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 r UTF-8 or UTF-1
27b60 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 6 respectively..
27b70 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 ** ^(Memory to h
27b80 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 old the error me
27b90 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
27ba0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c managed internal
27bb0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 ly..** The appli
27bc0 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 cation does not
27bd0 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 need to worry ab
27be0 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 out freeing the
27bf0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 result..** Howev
27c00 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 er, the error st
27c10 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 ring might be ov
27c20 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 erwritten or dea
27c30 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 llocated by.** s
27c40 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
27c50 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 to other SQLite
27c60 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 interface functi
27c70 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ons.)^.**.** ^Th
27c80 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 e sqlite3_errstr
27c90 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
27ca0 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 urns the English
27cb0 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a -language text.*
27cc0 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 * that describes
27cd0 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 the [result cod
27ce0 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a e], as UTF-8..**
27cf0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c ^(Memory to hol
27d00 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 d the error mess
27d10 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 age string is ma
27d20 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 naged internally
27d30 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 .** and must not
27d40 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 be freed by the
27d50 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a application)^..
27d60 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 **.** When the s
27d70 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
27d80 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e ding mode] is in
27d90 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 use, it might b
27da0 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 e the.** case th
27db0 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f at a second erro
27dc0 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 r occurs on a se
27dd0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e parate thread in
27de0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 between.** the
27df0 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 time of the firs
27e00 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 t error and the
27e10 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e call to these in
27e20 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 terfaces..** Whe
27e30 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 n that happens,
27e40 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 the second error
27e50 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 will be reporte
27e60 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a d since these.**
27e70 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 interfaces alwa
27e80 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f ys report the mo
27e90 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 st recent result
27ea0 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 . To avoid.** t
27eb0 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 his, each thread
27ec0 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c can obtain excl
27ed0 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 usive use of the
27ee0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
27ef0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 ction] D.** by i
27f00 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 nvoking [sqlite3
27f10 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 _mutex_enter]([s
27f20 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d qlite3_db_mutex]
27f30 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 (D)) before begi
27f40 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 nning.** to use
27f50 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b D and invoking [
27f60 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 sqlite3_mutex_le
27f70 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 ave]([sqlite3_db
27f80 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 _mutex](D)) afte
27f90 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 r.** all calls t
27fa0 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 o the interfaces
27fb0 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 listed here are
27fc0 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a completed..**.*
27fd0 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 * If an interfac
27fe0 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c e fails with SQL
27ff0 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 ITE_MISUSE, that
28000 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 means the inter
28010 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f face.** was invo
28020 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 ked incorrectly
28030 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
28040 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 on. In that cas
28050 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 e, the.** error
28060 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 code and message
28070 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 may or may not
28080 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 be set..*/.SQLIT
28090 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
280a0 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 _APICALL sqlite3
280b0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 _errcode(sqlite3
280c0 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 *db);.SQLITE_AP
280d0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 I int SQLITE_API
280e0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74 CALL sqlite3_ext
280f0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 ended_errcode(sq
28100 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 lite3 *db);.SQLI
28110 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
28120 72 20 2a 53 51 4c 49 54 45 5f 41 50 49 43 41 4c r *SQLITE_APICAL
28130 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 L sqlite3_errmsg
28140 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 (sqlite3*);.SQLI
28150 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
28160 64 20 2a 53 51 4c 49 54 45 5f 41 50 49 43 41 4c d *SQLITE_APICAL
28170 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 L sqlite3_errmsg
28180 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 16(sqlite3*);.SQ
28190 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
281a0 68 61 72 20 2a 53 51 4c 49 54 45 5f 41 50 49 43 har *SQLITE_APIC
281b0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 73 ALL sqlite3_errs
281c0 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 tr(int);../*.**
281d0 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 CAPI3REF: Prepar
281e0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a ed Statement Obj
281f0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ect.** KEYWORDS:
28200 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
28210 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 ment} {prepared
28220 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a statements}.**.*
28230 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
28240 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 this object rep
28250 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 resents a single
28260 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
28270 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 hat.** has been
28280 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 compiled into bi
28290 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 nary form and is
282a0 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 ready to be eva
282b0 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 luated..**.** Th
282c0 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 ink of each SQL
282d0 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 statement as a s
282e0 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 eparate computer
282f0 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a program. The.*
28300 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 * original SQL t
28310 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f ext is source co
28320 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 de. A prepared
28330 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 statement object
28340 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 .** is the comp
28350 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 iled object code
28360 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 . All SQL must
28370 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 be converted int
28380 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 o a.** prepared
28390 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 statement before
283a0 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a it can be run..
283b0 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 **.** The life-c
283c0 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 ycle of a prepar
283d0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a ed statement obj
283e0 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 ect usually goes
283f0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
28400 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 * <ol>.** <li> C
28410 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 reate the prepar
28420 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a ed statement obj
28430 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ect using [sqlit
28440 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
28450 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 ..** <li> Bind v
28460 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 alues to [parame
28470 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 ters] using the
28480 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
28490 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 .** interfa
284a0 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e ces..** <li> Run
284b0 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c the SQL by call
284c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
284d0 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 p()] one or more
284e0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 times..** <li>
284f0 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 Reset the prepar
28500 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 ed statement usi
28510 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
28520 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 t()] then go bac
28530 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 k.** to ste
28540 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 p 2. Do this ze
28550 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ro or more times
28560 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f ..** <li> Destro
28570 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 y the object usi
28580 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
28590 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c lize()]..** </ol
285a0 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 >.*/.typedef str
285b0 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 uct sqlite3_stmt
285c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a sqlite3_stmt;..
285d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
285e0 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a Run-time Limits.
285f0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
28600 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 e3.**.** ^(This
28610 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 interface allows
28620 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 the size of var
28630 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 ious constructs
28640 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a to be limited.**
28650 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e on a connection
28660 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 by connection b
28670 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 asis. The first
28680 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
28690 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
286a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 onnection] whose
286b0 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 limit is to be
286c0 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 set or queried.
286d0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 The.** second p
286e0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 arameter is one
286f0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 of the [limit ca
28700 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 tegories] that d
28710 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 efine a.** class
28720 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 of constructs t
28730 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 o be size limite
28740 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 d. The third pa
28750 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
28760 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 * new limit for
28770 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 that construct.)
28780 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ^.**.** ^If the
28790 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e new limit is a n
287a0 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 egative number,
287b0 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 the limit is unc
287c0 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 hanged..** ^(For
287d0 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 each limit cate
287e0 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 gory SQLITE_LIMI
287f0 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 T_<i>NAME</i> th
28800 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 ere is a .** [li
28810 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 mits | hard uppe
28820 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 r bound].** set
28830 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
28840 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 by a C preproces
28850 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 sor macro called
28860 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 .** [limits | SQ
28870 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 LITE_MAX_<i>NAME
28880 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 </i>]..** (The "
28890 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 _LIMIT_" in the
288a0 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 name is changed
288b0 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a to "_MAX_".))^.*
288c0 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 * ^Attempts to i
288d0 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 ncrease a limit
288e0 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 above its hard u
288f0 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a pper bound are.*
28900 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 * silently trunc
28910 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 ated to the hard
28920 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a upper bound..**
28930 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 .** ^Regardless
28940 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
28950 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 t the limit was
28960 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a changed, the .**
28970 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
28980 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
28990 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 urns the prior v
289a0 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 alue of the limi
289b0 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f t..** ^Hence, to
289c0 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e find the curren
289d0 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d t value of a lim
289e0 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 it without chang
289f0 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c ing it,.** simpl
28a00 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e y invoke this in
28a10 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 terface with the
28a20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
28a30 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a set to -1..**.*
28a40 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 * Run-time limit
28a50 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
28a60 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 or use in applic
28a70 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 ations that mana
28a80 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 ge.** both their
28a90 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 own internal da
28aa0 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 tabase and also
28ab0 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 databases that a
28ac0 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a re controlled.**
28ad0 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 by untrusted ex
28ae0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 ternal sources.
28af0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c An example appl
28b00 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 ication might be
28b10 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 a.** web browse
28b20 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f r that has its o
28b30 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 wn databases for
28b40 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 storing history
28b50 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 and.** separate
28b60 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 databases contr
28b70 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 olled by JavaScr
28b80 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ipt applications
28b90 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f downloaded.** o
28ba0 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e ff the Internet.
28bb0 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 The internal d
28bc0 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 atabases can be
28bd0 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 given the.** lar
28be0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 ge, default limi
28bf0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d ts. Databases m
28c00 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e anaged by extern
28c10 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a al sources can.*
28c20 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 * be given much
28c30 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 smaller limits d
28c40 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 esigned to preve
28c50 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 nt a denial of s
28c60 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b ervice.** attack
28c70 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 . Developers mi
28c80 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f ght also want to
28c90 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 use the [sqlite
28ca0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
28cb0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
28cc0 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 to further cont
28cd0 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 rol untrusted SQ
28ce0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 L. The size of
28cf0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
28d00 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e created by an un
28d10 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 trusted script c
28d20 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 an be contained
28d30 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 using the.** [ma
28d40 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 x_page_count] [P
28d50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 RAGMA]..**.** Ne
28d60 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 w run-time limit
28d70 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 categories may
28d80 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
28d90 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a re releases..*/.
28da0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
28db0 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 QLITE_APICALL sq
28dc0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 lite3_limit(sqli
28dd0 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e te3*, int id, in
28de0 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a t newVal);../*.*
28df0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
28e00 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 Time Limit Categ
28e10 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 ories.** KEYWORD
28e20 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f S: {limit catego
28e30 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 ry} {*limit cate
28e40 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 gories}.**.** Th
28e50 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 ese constants de
28e60 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 fine various per
28e70 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a formance limits.
28e80 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c ** that can be l
28e90 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 owered at run-ti
28ea0 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 me using [sqlite
28eb0 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 3_limit()]..** T
28ec0 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 he synopsis of t
28ed0 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 he meanings of t
28ee0 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 he various limit
28ef0 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 s is shown below
28f00 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 ..** Additional
28f10 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 information is a
28f20 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d vailable at [lim
28f30 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 its | Limits in
28f40 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c SQLite]..**.** <
28f50 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f dl>.** [[SQLITE_
28f60 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e LIMIT_LENGTH]] ^
28f70 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
28f80 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a T_LENGTH</dt>.**
28f90 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
28fa0 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 size of any str
28fb0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 ing or BLOB or t
28fc0 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 able row, in byt
28fd0 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 es.<dd>)^.**.**
28fe0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 [[SQLITE_LIMIT_S
28ff0 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 QL_LENGTH]] ^(<d
29000 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 t>SQLITE_LIMIT_S
29010 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a QL_LENGTH</dt>.*
29020 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
29030 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 m length of an S
29040 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e QL statement, in
29050 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a bytes.</dd>)^.*
29060 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
29070 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c MIT_COLUMN]] ^(<
29080 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
29090 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c COLUMN</dt>.** <
290a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
290b0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
290c0 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 in a table defi
290d0 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 nition or in the
290e0 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f .** result set o
290f0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 f a [SELECT] or
29100 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 the maximum numb
29110 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
29120 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 an index.** or
29130 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f in an ORDER BY o
29140 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 r GROUP BY claus
29150 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 e.</dd>)^.**.**
29160 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 [[SQLITE_LIMIT_E
29170 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 XPR_DEPTH]] ^(<d
29180 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 t>SQLITE_LIMIT_E
29190 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a XPR_DEPTH</dt>.*
291a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
291b0 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 m depth of the p
291c0 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 arse tree on any
291d0 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 expression.</dd
291e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
291f0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
29200 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 D_SELECT]] ^(<dt
29210 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f >SQLITE_LIMIT_CO
29220 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 MPOUND_SELECT</d
29230 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
29240 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
29250 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f terms in a compo
29260 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 und SELECT state
29270 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ment.</dd>)^.**.
29280 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
29290 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 T_VDBE_OP]] ^(<d
292a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 t>SQLITE_LIMIT_V
292b0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c DBE_OP</dt>.** <
292c0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
292d0 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 umber of instruc
292e0 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 tions in a virtu
292f0 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 al machine progr
29300 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d am.** used to im
29310 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 plement an SQL s
29320 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 tatement. This
29330 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 limit is not cur
29340 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 rently.** enforc
29350 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 ed, though that
29360 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 might be added i
29370 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 n some future re
29380 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 lease of.** SQLi
29390 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a te.</dd>)^.**.**
293a0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
293b0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e FUNCTION_ARG]] ^
293c0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
293d0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f T_FUNCTION_ARG</
293e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
293f0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
29400 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 arguments on a
29410 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e function.</dd>)^
29420 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
29430 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d LIMIT_ATTACHED]]
29440 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
29450 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 MIT_ATTACHED</dt
29460 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
29470 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b imum number of [
29480 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 ATTACH | attache
29490 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c d databases].)^<
294a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
294b0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 ITE_LIMIT_LIKE_P
294c0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a ATTERN_LENGTH]].
294d0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ** ^(<dt>SQLITE_
294e0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
294f0 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a RN_LENGTH</dt>.*
29500 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
29510 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 m length of the
29520 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 pattern argument
29530 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f to the [LIKE] o
29540 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 r.** [GLOB] oper
29550 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ators.</dd>)^.**
29560 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
29570 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
29580 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 ER]].** ^(<dt>SQ
29590 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
295a0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a BLE_NUMBER</dt>.
295b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
295c0 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 um index number
295d0 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 of any [paramete
295e0 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 r] in an SQL sta
295f0 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 tement.)^.**.**
29600 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 [[SQLITE_LIMIT_T
29610 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e RIGGER_DEPTH]] ^
29620 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
29630 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c T_TRIGGER_DEPTH<
29640 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
29650 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 maximum depth of
29660 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 recursion for t
29670 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a riggers.</dd>)^.
29680 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
29690 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 IMIT_WORKER_THRE
296a0 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 ADS]] ^(<dt>SQLI
296b0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f TE_LIMIT_WORKER_
296c0 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 THREADS</dt>.**
296d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
296e0 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 number of auxili
296f0 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 ary worker threa
29700 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 ds that a single
29710 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
29720 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 atement] may sta
29730 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f rt.</dd>)^.** </
29740 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
29750 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
29760 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
29770 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 0.#define
29780 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c SQLITE_LIMIT_SQL
29790 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
297a0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
297b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f SQLITE_LIMIT_CO
297c0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 LUMN
297d0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
297e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 e SQLITE_LIMIT_E
297f0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 XPR_DEPTH
29800 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 3.#defi
29810 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
29820 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 COMPOUND_SELECT
29830 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
29840 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
29850 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 _VDBE_OP
29860 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 5.#de
29870 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
29880 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 T_FUNCTION_ARG
29890 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 6.#d
298a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
298b0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 IT_ATTACHED
298c0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 7.#
298d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
298e0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MIT_LIKE_PATTERN
298f0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a _LENGTH 8.
29900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
29910 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
29920 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 MBER 9
29930 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
29940 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 LIMIT_TRIGGER_DE
29950 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 PTH 1
29960 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
29970 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 _LIMIT_WORKER_TH
29980 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20 READS
29990 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 11../*.** CAPI3R
299a0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e EF: Compiling An
299b0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a SQL Statement.*
299c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c * KEYWORDS: {SQL
299d0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 statement compi
299e0 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ler}.** METHOD:
299f0 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 sqlite3.** CONST
29a00 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f RUCTOR: sqlite3_
29a10 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 stmt.**.** To ex
29a20 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 ecute an SQL que
29a30 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 ry, it must firs
29a40 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e t be compiled in
29a50 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a to a byte-code.*
29a60 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 * program using
29a70 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 one of these rou
29a80 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tines..**.** The
29a90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c first argument,
29aa0 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 "db", is a [dat
29ab0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
29ac0 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 ] obtained from
29ad0 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 a.** prior succe
29ae0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
29af0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
29b00 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
29b10 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
29b20 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 e3_open16()]. T
29b30 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
29b40 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 ection must not
29b50 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 have been closed
29b60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f ..**.** The seco
29b70 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 nd argument, "zS
29b80 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 ql", is the stat
29b90 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 ement to be comp
29ba0 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a iled, encoded.**
29bb0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
29bc0 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 or UTF-16. The
29bd0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
29be0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
29bf0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 repare_v2().** i
29c00 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 nterfaces use UT
29c10 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 F-8, and sqlite3
29c20 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 _prepare16() and
29c30 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
29c40 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 16_v2().** use U
29c50 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 TF-16..**.** ^If
29c60 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d the nByte argum
29c70 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c ent is negative,
29c80 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 then zSql is re
29c90 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 ad up to the.**
29ca0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
29cb0 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 nator. ^If nByte
29cc0 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 is positive, th
29cd0 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 en it is the.**
29ce0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
29cf0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 read from zSql.
29d00 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 ^If nByte is ze
29d10 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 ro, then no prep
29d20 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e ared.** statemen
29d30 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a t is generated..
29d40 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 ** If the caller
29d50 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 knows that the
29d60 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 supplied string
29d70 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 is nul-terminate
29d80 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 d, then.** there
29d90 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 is a small perf
29da0 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 ormance advantag
29db0 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 e to passing an
29dc0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 nByte parameter
29dd0 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e that.** is the n
29de0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
29df0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 n the input stri
29e00 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c ng <i>including<
29e10 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 /i>.** the nul-t
29e20 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a erminator..**.**
29e30 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e ^If pzTail is n
29e40 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a ot NULL then *pz
29e50 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 Tail is made to
29e60 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 point to the fir
29e70 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 st byte.** past
29e80 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 the end of the f
29e90 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 irst SQL stateme
29ea0 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 nt in zSql. The
29eb0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 se routines only
29ec0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 .** compile the
29ed0 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 first statement
29ee0 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 in zSql, so *pzT
29ef0 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e ail is left poin
29f00 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 ting to.** what
29f10 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c remains uncompil
29f20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 ed..**.** ^*ppSt
29f30 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 mt is left point
29f40 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 ing to a compile
29f50 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
29f60 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 ement] that can
29f70 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 be.** executed u
29f80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 sing [sqlite3_st
29f90 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 ep()]. ^If ther
29fa0 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a e is an error, *
29fb0 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a ppStmt is set.**
29fc0 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 to NULL. ^If t
29fd0 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f he input text co
29fe0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 ntains no SQL (i
29ff0 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 f the input is a
2a000 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e n empty.** strin
2a010 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 g or a comment)
2a020 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 then *ppStmt is
2a030 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 set to NULL..**
2a040 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 The calling proc
2a050 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 edure is respons
2a060 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e ible for deletin
2a070 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a g the compiled.*
2a080 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 * SQL statement
2a090 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
2a0a0 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 inalize()] after
2a0b0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 it has finished
2a0c0 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 with it..** ppS
2a0d0 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e tmt may not be N
2a0e0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 ULL..**.** ^On s
2a0f0 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 uccess, the sqli
2a100 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 te3_prepare() fa
2a110 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 mily of routines
2a120 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
2a130 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 OK];.** otherwis
2a140 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 e an [error code
2a150 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
2a160 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
2a170 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e _prepare_v2() an
2a180 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
2a190 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 e16_v2() interfa
2a1a0 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d ces are.** recom
2a1b0 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e mended for all n
2a1c0 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 ew programs. The
2a1d0 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 two older inter
2a1e0 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e faces are retain
2a1f0 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 ed.** for backwa
2a200 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
2a210 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 y, but their use
2a220 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e is discouraged.
2a230 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 .** ^In the "v2"
2a240 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
2a250 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2a260 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 ent.** that is r
2a270 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 eturned (the [sq
2a280 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
2a290 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 ct) contains a c
2a2a0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 opy of the.** or
2a2b0 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e iginal SQL text.
2a2c0 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 This causes the
2a2d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2a2e0 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a ] interface to.*
2a2f0 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 * behave differe
2a300 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 ntly in three wa
2a310 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a ys:.**.** <ol>.*
2a320 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 * <li>.** ^If th
2a330 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
2a340 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 a changes, inste
2a350 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 ad of returning
2a360 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 [SQLITE_SCHEMA]
2a370 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 as it.** always
2a380 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c used to do, [sql
2a390 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
2a3a0 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 l automatically
2a3b0 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 recompile the SQ
2a3c0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 L.** statement a
2a3d0 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 nd try to run it
2a3e0 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 again. As many
2a3f0 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 as [SQLITE_MAX_S
2a400 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 CHEMA_RETRY].**
2a410 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 retries will occ
2a420 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 ur before sqlite
2a430 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 3_step() gives u
2a440 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e p and returns an
2a450 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e error..** </li>
2a460 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e .**.** <li>.** ^
2a470 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 When an error oc
2a480 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 curs, [sqlite3_s
2a490 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 tep()] will retu
2a4a0 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 rn one of the de
2a4b0 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 tailed.** [error
2a4c0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 codes] or [exte
2a4d0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 nded error codes
2a4e0 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 ]. ^The legacy
2a4f0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 behavior was tha
2a500 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 t.** [sqlite3_st
2a510 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 ep()] would only
2a520 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 return a generi
2a530 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d c [SQLITE_ERROR]
2a540 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 result code.**
2a550 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 and the applicat
2a560 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 ion would have t
2a570 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 o make a second
2a580 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2a590 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 _reset()].** in
2a5a0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 order to find th
2a5b0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 e underlying cau
2a5c0 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 se of the proble
2a5d0 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 m. With the "v2"
2a5e0 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 prepare.** inte
2a5f0 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 rfaces, the unde
2a600 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f rlying reason fo
2a610 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 r the error is r
2a620 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 eturned immediat
2a630 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a ely..** </li>.**
2a640 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 .** <li>.** ^If
2a650 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c the specific val
2a660 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 ue bound to [par
2a670 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 ameter | host pa
2a680 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 rameter] in the
2a690 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 .** WHERE clause
2a6a0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 might influence
2a6b0 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 the choice of q
2a6c0 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 uery plan for a
2a6d0 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 statement,.** th
2a6e0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 en the statement
2a6f0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
2a700 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 ically recompile
2a710 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 d, as if there h
2a720 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 ad been .** a sc
2a730 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 hema change, on
2a740 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 the first [sqli
2a750 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c te3_step()] call
2a760 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 following any c
2a770 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 hange.** to the
2a780 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 [sqlite3_bind_te
2a790 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f xt | bindings] o
2a7a0 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 f that [paramete
2a7b0 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 r]. .** ^The spe
2a7c0 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 cific value of W
2a7d0 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 HERE-clause [par
2a7e0 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e ameter] might in
2a7f0 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 fluence the .**
2a800 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 choice of query
2a810 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 plan if the para
2a820 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 meter is the lef
2a830 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 t-hand side of a
2a840 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 [LIKE].** or [G
2a850 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 LOB] operator or
2a860 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
2a870 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f r is compared to
2a880 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 an indexed colu
2a890 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 mn.** and the [S
2a8a0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 QLITE_ENABLE_STA
2a8b0 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 T3] compile-time
2a8c0 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c option is enabl
2a8d0 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 ed..** </li>.**
2a8e0 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f </ol>.*/.SQLITE_
2a8f0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 API int SQLITE_A
2a900 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 PICALL sqlite3_p
2a910 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 repare(. sqlite
2a920 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
2a930 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
2a940 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2a950 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
2a960 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
2a970 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 nt, UTF-8 encode
2a980 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
2a990 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
2a9a0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
2a9b0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
2a9c0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
2a9d0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
2a9e0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
2a9f0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
2aa00 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 nst char **pzTai
2aa10 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
2aa20 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
2aa30 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
2aa40 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 */.);.SQLITE_API
2aa50 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 int SQLITE_APIC
2aa60 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 ALL sqlite3_prep
2aa70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 are_v2(. sqlite
2aa80 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
2aa90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
2aaa0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2aab0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
2aac0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
2aad0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 nt, UTF-8 encode
2aae0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
2aaf0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
2ab00 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
2ab10 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
2ab20 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
2ab30 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
2ab40 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
2ab50 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
2ab60 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 nst char **pzTai
2ab70 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
2ab80 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
2ab90 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
2aba0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 */.);.SQLITE_API
2abb0 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 int SQLITE_APIC
2abc0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 ALL sqlite3_prep
2abd0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 are16(. sqlite3
2abe0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
2abf0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
2ac00 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
2ac10 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 oid *zSql,
2ac20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
2ac30 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 t, UTF-16 encode
2ac40 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
2ac50 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
2ac60 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
2ac70 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
2ac80 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
2ac90 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
2aca0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
2acb0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
2acc0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 nst void **pzTai
2acd0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
2ace0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
2acf0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
2ad00 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 */.);.SQLITE_API
2ad10 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 int SQLITE_APIC
2ad20 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 ALL sqlite3_prep
2ad30 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 are16_v2(. sqli
2ad40 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
2ad50 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
2ad60 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
2ad70 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
2ad80 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
2ad90 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
2ada0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
2adb0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
2adc0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
2add0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
2ade0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
2adf0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
2ae00 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
2ae10 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
2ae20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
2ae30 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
2ae40 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
2ae50 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
2ae60 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ql */.);../*.**
2ae70 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 CAPI3REF: Retrie
2ae80 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 ving Statement S
2ae90 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 QL.** METHOD: sq
2aea0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2aeb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 ^The sqlite3_sq
2aec0 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 l(P) interface r
2aed0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
2aee0 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 to a copy of th
2aef0 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 e UTF-8.** SQL t
2af00 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 ext used to crea
2af10 74 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 te [prepared sta
2af20 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 tement] P if P w
2af30 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 as.** created by
2af40 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
2af50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
2af60 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
2af70 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e re16_v2()]..** ^
2af80 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 The sqlite3_expa
2af90 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 nded_sql(P) inte
2afa0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
2afb0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 pointer to a UTF
2afc0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e -8.** string con
2afd0 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 taining the SQL
2afe0 74 65 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 text of prepared
2aff0 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 statement P wit
2b000 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 h.** [bound para
2b010 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 meters] expanded
2b020 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 ..**.** ^(For ex
2b030 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70 ample, if a prep
2b040 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 ared statement i
2b050 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 s created using
2b060 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 the SQL.** text
2b070 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 "SELECT $abc,:xy
2b080 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65 z" and if parame
2b090 74 65 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e ter $abc is boun
2b0a0 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34 d to integer 234
2b0b0 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 5.** and paramet
2b0c0 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 er :xyz is unbou
2b0d0 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 nd, then sqlite3
2b0e0 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 _sql() will retu
2b0f0 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e rn.** the origin
2b100 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 al string, "SELE
2b110 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 CT $abc,:xyz" bu
2b120 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 t sqlite3_expand
2b130 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c ed_sql().** will
2b140 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20 return "SELECT
2b150 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 2345,NULL".)^.**
2b160 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2b170 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 _expanded_sql()
2b180 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2b190 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 s NULL if insuff
2b1a0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a icient memory.**
2b1b0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f is available to
2b1c0 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 hold the result
2b1d0 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 73 75 , or if the resu
2b1e0 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 lt would exceed
2b1f0 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d the.** the maxim
2b200 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 um string length
2b210 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 determined by t
2b220 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 he [SQLITE_LIMIT
2b230 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 _LENGTH]..**.**
2b240 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 ^The [SQLITE_TRA
2b250 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 CE_SIZE_LIMIT] c
2b260 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
2b270 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 on limits the si
2b280 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 ze of.** bound p
2b290 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69 arameter expansi
2b2a0 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 ons. ^The [SQLI
2b2b0 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 TE_OMIT_TRACE] c
2b2c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f ompile-time.** o
2b2d0 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c ption causes sql
2b2e0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 ite3_expanded_sq
2b2f0 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65 l() to always re
2b300 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a turn NULL..**.**
2b310 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 ^The string ret
2b320 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
2b330 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 _sql(P) is manag
2b340 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 ed by SQLite and
2b350 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 is.** automatic
2b360 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65 6e 20 ally freed when
2b370 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 the prepared sta
2b380 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 tement is finali
2b390 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 zed..** ^The str
2b3a0 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 ing returned by
2b3b0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 sqlite3_expanded
2b3c0 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 _sql(P), on the
2b3d0 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 other hand,.** i
2b3e0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 s obtained from
2b3f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
2b400 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 )] and must be f
2b410 72 65 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 ree by the appli
2b420 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 cation.** by pas
2b430 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 sing it to [sqli
2b440 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a te3_free()]..*/.
2b450 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2b460 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 41 50 char *SQLITE_AP
2b470 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 71 ICALL sqlite3_sq
2b480 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a l(sqlite3_stmt *
2b490 70 53 74 6d 74 29 3b 0a 53 51 4c 49 54 45 5f 41 pStmt);.SQLITE_A
2b4a0 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f PI char *SQLITE_
2b4b0 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f APICALL sqlite3_
2b4c0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c expanded_sql(sql
2b4d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
2b4e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2b4f0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 EF: Determine If
2b500 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
2b510 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 t Writes The Dat
2b520 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a abase.** METHOD:
2b530 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2b540 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2b550 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 _stmt_readonly(X
2b560 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2b570 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 rns true (non-ze
2b580 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e ro) if.** and on
2b590 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 ly if the [prepa
2b5a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 red statement] X
2b5b0 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 makes no direct
2b5c0 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 changes to.** t
2b5d0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
2b5e0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e e database file.
2b5f0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
2b600 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 [application-de
2b610 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
2b620 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 ons] or.** [virt
2b630 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 ual tables] migh
2b640 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 t change the dat
2b650 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 abase indirectly
2b660 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 as a side effec
2b670 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 t. .** ^(For ex
2b680 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 ample, if an app
2b690 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 lication defines
2b6a0 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 a function "eva
2b6b0 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 l()" that .** ca
2b6c0 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 lls [sqlite3_exe
2b6d0 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 c()], then the f
2b6e0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 ollowing SQL sta
2b6f0 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 tement would.**
2b700 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 change the datab
2b710 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 ase file through
2b720 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a side-effects:.*
2b730 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
2b740 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c ><pre>.** SEL
2b750 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 ECT eval('DELETE
2b760 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 FROM t1') FROM
2b770 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 t2;.** </pre></b
2b780 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
2b790 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 But because the
2b7a0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
2b7b0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 ent does not cha
2b7c0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 nge the database
2b7d0 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c file.** directl
2b7e0 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f y, sqlite3_stmt_
2b7f0 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 readonly() would
2b800 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 still return tr
2b810 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 ue.)^.**.** ^Tra
2b820 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c nsaction control
2b830 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 statements such
2b840 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f as [BEGIN], [CO
2b850 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b MMIT], [ROLLBACK
2b860 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 ],.** [SAVEPOINT
2b870 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d ], and [RELEASE]
2b880 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 cause sqlite3_s
2b890 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 tmt_readonly() t
2b8a0 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a o return true,.*
2b8b0 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 * since the stat
2b8c0 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 ements themselve
2b8d0 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c s do not actuall
2b8e0 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 y modify the dat
2b8f0 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 abase but.** rat
2b900 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c her they control
2b910 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 the timing of w
2b920 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d hen other statem
2b930 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 ents modify the
2b940 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e .** database. ^
2b950 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 The [ATTACH] and
2b960 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d [DETACH] statem
2b970 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a ents also cause.
2b980 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f ** sqlite3_stmt_
2b990 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 readonly() to re
2b9a0 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c turn true since,
2b9b0 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 while those sta
2b9c0 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 tements.** chang
2b9d0 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 e the configurat
2b9e0 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 ion of a databas
2b9f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 e connection, th
2ba00 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a ey do not make .
2ba10 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 ** changes to th
2ba20 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
2ba30 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 database files
2ba40 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 on disk..*/.SQLI
2ba50 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2ba60 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 E_APICALL sqlite
2ba70 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
2ba80 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
2ba90 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
2baa0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 I3REF: Determine
2bab0 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 If A Prepared S
2bac0 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 tatement Has Bee
2bad0 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f n Reset.** METHO
2bae0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
2baf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2bb00 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 e3_stmt_busy(S)
2bb10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2bb20 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f s true (non-zero
2bb30 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 ) if the.** [pre
2bb40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2bb50 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 S has been step
2bb60 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 ped at least onc
2bb70 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c e using .** [sql
2bb80 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 ite3_step(S)] bu
2bb90 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 t has neither ru
2bba0 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 n to completion
2bbb0 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 (returned.** [SQ
2bbc0 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 LITE_DONE] from
2bbd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
2bbe0 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 ]) nor.** been r
2bbf0 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 eset using [sqli
2bc00 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 te3_reset(S)].
2bc10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d ^The sqlite3_stm
2bc20 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 t_busy(S).** int
2bc30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 erface returns f
2bc40 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e alse if S is a N
2bc50 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 ULL pointer. If
2bc60 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 S is not a .**
2bc70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 NULL pointer and
2bc80 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 is not a pointe
2bc90 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 r to a valid [pr
2bca0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2bcb0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 ].** object, the
2bcc0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
2bcd0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
2bce0 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 probably undesir
2bcf0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 able..**.** This
2bd00 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
2bd10 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e e used in combin
2bd20 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e ation [sqlite3_n
2bd30 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 ext_stmt()].** t
2bd40 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 o locate all pre
2bd50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
2bd60 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
2bd70 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 a database .**
2bd80 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
2bd90 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 are in need of b
2bda0 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 eing reset. Thi
2bdb0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a s can be used,.*
2bdc0 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 * for example, i
2bdd0 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 n diagnostic rou
2bde0 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 tines to search
2bdf0 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a for prepared .**
2be00 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 statements that
2be10 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 are holding a t
2be20 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e ransaction open.
2be30 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2be40 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c nt SQLITE_APICAL
2be50 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 L sqlite3_stmt_b
2be60 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 usy(sqlite3_stmt
2be70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
2be80 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 REF: Dynamically
2be90 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a Typed Value Obj
2bea0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ect.** KEYWORDS:
2beb0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 {protected sqli
2bec0 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 te3_value} {unpr
2bed0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2bee0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c value}.**.** SQL
2bef0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c ite uses the sql
2bf00 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2bf10 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 t to represent a
2bf20 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 ll values.** tha
2bf30 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 t can be stored
2bf40 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 in a database ta
2bf50 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 ble. SQLite uses
2bf60 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a dynamic typing.
2bf70 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 ** for the value
2bf80 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 s it stores. ^V
2bf90 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 alues stored in
2bfa0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2bfb0 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 jects.** can be
2bfc0 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 integers, floati
2bfd0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c ng point values,
2bfe0 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c strings, BLOBs,
2bff0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 or NULL..**.**
2c000 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 An sqlite3_value
2c010 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 object may be e
2c020 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 ither "protected
2c030 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 " or "unprotecte
2c040 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 d"..** Some inte
2c050 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 rfaces require a
2c060 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
2c070 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 e3_value. Other
2c080 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 interfaces.** w
2c090 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 ill accept eithe
2c0a0 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 r a protected or
2c0b0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 an unprotected
2c0c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a sqlite3_value..*
2c0d0 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 * Every interfac
2c0e0 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 e that accepts s
2c0f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 qlite3_value arg
2c100 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 uments specifies
2c110 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e .** whether or n
2c120 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 ot it requires a
2c130 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
2c140 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a e3_value. The.*
2c150 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 * [sqlite3_value
2c160 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 _dup()] interfac
2c170 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
2c180 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 construct a new
2c190 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 .** protected s
2c1a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f qlite3_value fro
2c1b0 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 m an unprotected
2c1c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a sqlite3_value..
2c1d0 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 **.** The terms
2c1e0 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 "protected" and
2c1f0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 "unprotected" re
2c200 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f fer to whether o
2c210 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 r not.** a mutex
2c220 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e is held. An in
2c230 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 ternal mutex is
2c240 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 held for a prote
2c250 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
2c260 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 value object but
2c270 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c no mutex is hel
2c280 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 d for an unprote
2c290 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
2c2a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 value object. I
2c2b0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
2c2c0 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c iled to be singl
2c2d0 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 e-threaded.** (w
2c2e0 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 ith [SQLITE_THRE
2c2f0 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 ADSAFE=0] and wi
2c300 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 th [sqlite3_thre
2c310 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e adsafe()] return
2c320 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 ing 0).** or if
2c330 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e SQLite is run in
2c340 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 one of reduced
2c350 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 mutex modes .**
2c360 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
2c370 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 INGLETHREAD] or
2c380 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
2c390 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 ULTITHREAD].** t
2c3a0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 hen there is no
2c3b0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 distinction betw
2c3c0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e een protected an
2c3d0 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a d unprotected.**
2c3e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2c3f0 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 bjects and they
2c400 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 can be used inte
2c410 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f rchangeably. Ho
2c420 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 wever,.** for ma
2c430 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 ximum code porta
2c440 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 bility it is rec
2c450 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
2c460 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 plications.** st
2c470 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 ill make the dis
2c480 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e tinction between
2c490 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 protected and u
2c4a0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 nprotected.** sq
2c4b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2c4c0 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f cts even when no
2c4d0 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 t strictly requi
2c4e0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 red..**.** ^The
2c4f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2c500 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 jects that are p
2c510 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 assed as paramet
2c520 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 ers into the.**
2c530 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
2c540 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 f [application-d
2c550 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
2c560 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 ions] are protec
2c570 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ted..** ^The sql
2c580 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2c590 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
2c5a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2c5b0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 _value()] is unp
2c5c0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 rotected..** Unp
2c5d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2c5e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d _value objects m
2c5f0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 ay only be used
2c600 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 with.** [sqlite3
2c610 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d _result_value()]
2c620 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 and [sqlite3_bi
2c630 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 nd_value()]..**
2c640 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c The [sqlite3_val
2c650 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 ue_blob | sqlite
2c660 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 3_value_type()]
2c670 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 family of.** int
2c680 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
2c690 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2c6a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 3_value objects.
2c6b0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
2c6c0 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 ct Mem sqlite3_v
2c6d0 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 alue;../*.** CAP
2c6e0 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 I3REF: SQL Funct
2c6f0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 ion Context Obje
2c700 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e ct.**.** The con
2c710 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e text in which an
2c720 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 SQL function ex
2c730 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 ecutes is stored
2c740 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 in an.** sqlite
2c750 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 3_context object
2c760 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f . ^A pointer to
2c770 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 an sqlite3_cont
2c780 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 ext object.** is
2c790 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 always first pa
2c7a0 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c rameter to [appl
2c7b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2c7c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a SQL functions]..
2c7d0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
2c7e0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
2c7f0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
2c800 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 tation will pass
2c810 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 this.** pointer
2c820 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 through into ca
2c830 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
2c840 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c result_int | sql
2c850 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a ite3_result()],.
2c860 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 ** [sqlite3_aggr
2c870 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d egate_context()]
2c880 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f , [sqlite3_user_
2c890 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c data()],.** [sql
2c8a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f ite3_context_db_
2c8b0 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 handle()], [sqli
2c8c0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
2c8d0 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 )],.** and/or [s
2c8e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
2c8f0 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 ta()]..*/.typede
2c900 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
2c910 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 _context sqlite3
2c920 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a _context;../*.**
2c930 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 CAPI3REF: Bindi
2c940 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 ng Values To Pre
2c950 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 pared Statements
2c960 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 .** KEYWORDS: {h
2c970 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b ost parameter} {
2c980 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d host parameters}
2c990 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
2c9a0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 name}.** KEYWOR
2c9b0 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 DS: {SQL paramet
2c9c0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 er} {SQL paramet
2c9d0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 ers} {parameter
2c9e0 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 binding}.** METH
2c9f0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2ca00 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 .**.** ^(In the
2ca10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 SQL statement te
2ca20 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c xt input to [sql
2ca30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2ca40 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 )] and its varia
2ca50 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 nts,.** literals
2ca60 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 may be replaced
2ca70 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 by a [parameter
2ca80 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f ] that matches o
2ca90 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a ne of following.
2caa0 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a ** templates:.**
2cab0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
2cac0 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e ?.** <li> ?NN
2cad0 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a N.** <li> :VVV.
2cae0 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a ** <li> @VVV.**
2caf0 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c <li> $VVV.** <
2cb00 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 /ul>.**.** In th
2cb10 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 e templates abov
2cb20 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 e, NNN represent
2cb30 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 s an integer lit
2cb40 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 eral,.** and VVV
2cb50 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 represents an a
2cb60 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e lphanumeric iden
2cb70 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 tifier.)^ ^The
2cb80 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a values of these.
2cb90 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 ** parameters (a
2cba0 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 lso called "host
2cbb0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 parameter names
2cbc0 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 " or "SQL parame
2cbd0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 ters").** can be
2cbe0 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 set using the s
2cbf0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
2cc00 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 routines defined
2cc10 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 here..**.** ^Th
2cc20 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
2cc30 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
2cc40 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
2cc50 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 s is always.** a
2cc60 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
2cc70 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f [sqlite3_stmt] o
2cc80 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 bject returned f
2cc90 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f rom.** [sqlite3_
2cca0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
2ccb0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a its variants..*
2ccc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 *.** ^The second
2ccd0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
2cce0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 index of the SQ
2ccf0 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 L parameter to b
2cd00 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c e set..** ^The l
2cd10 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 eftmost SQL para
2cd20 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 meter has an ind
2cd30 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 ex of 1. ^When
2cd40 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a the same named.*
2cd50 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 * SQL parameter
2cd60 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 is used more tha
2cd70 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 n once, second a
2cd80 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a nd subsequent.**
2cd90 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 occurrences hav
2cda0 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 e the same index
2cdb0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 as the first oc
2cdc0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 currence..** ^Th
2cdd0 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 e index for name
2cde0 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e d parameters can
2cdf0 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 be looked up us
2ce00 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
2ce10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2ce20 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 er_index()] API
2ce30 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 if desired. ^Th
2ce40 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 e index.** for "
2ce50 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 ?NNN" parameters
2ce60 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
2ce70 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e NNN..** ^The NN
2ce80 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 N value must be
2ce90 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 between 1 and th
2cea0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 e [sqlite3_limit
2ceb0 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ()].** parameter
2cec0 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 [SQLITE_LIMIT_V
2ced0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 ARIABLE_NUMBER]
2cee0 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 (default value:
2cef0 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 999)..**.** ^The
2cf00 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
2cf10 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 is the value to
2cf20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 bind to the para
2cf30 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 meter..** ^If th
2cf40 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
2cf50 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e r to sqlite3_bin
2cf60 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 d_text() or sqli
2cf70 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
2cf80 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
2cf90 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 bind_blob() is a
2cfa0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
2cfb0 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 en the fourth pa
2cfc0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 rameter.** is ig
2cfd0 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e nored and the en
2cfe0 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 d result is the
2cff0 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f same as sqlite3_
2d000 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a bind_null()..**.
2d010 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f ** ^(In those ro
2d020 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 utines that have
2d030 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 a fourth argume
2d040 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 nt, its value is
2d050 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
2d060 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 f bytes in the p
2d070 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 arameter. To be
2d080 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 clear: the valu
2d090 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
2d0a0 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f er of <u>bytes</
2d0b0 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c u> in the value,
2d0c0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 not the number
2d0d0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e of characters.)^
2d0e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 .** ^If the four
2d0f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
2d100 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2d110 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 t() or sqlite3_b
2d120 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 ind_text16().**
2d130 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
2d140 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 n the length of
2d150 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a the string is.**
2d160 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2d170 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 ytes up to the f
2d180 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e irst zero termin
2d190 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 ator..** If the
2d1a0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
2d1b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2d1c0 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 _blob() is negat
2d1d0 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 ive, then.** the
2d1e0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
2d1f0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 efined..** If a
2d200 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 non-negative fou
2d210 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
2d220 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c provided to sql
2d230 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
2d240 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 .** or sqlite3_b
2d250 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 ind_text16() or
2d260 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2d270 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 t64() then.** th
2d280 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 at parameter mus
2d290 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 t be the byte of
2d2a0 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 fset.** where th
2d2b0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 e NUL terminator
2d2c0 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 would occur ass
2d2d0 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 uming the string
2d2e0 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 were NUL.** ter
2d2f0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 minated. If any
2d300 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 NUL characters
2d310 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 occur at byte of
2d320 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 fsets less than
2d330 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 .** the value of
2d340 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
2d350 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 meter then the r
2d360 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 esulting string
2d370 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f value will.** co
2d380 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e ntain embedded N
2d390 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 ULs. The result
2d3a0 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 of expressions
2d3b0 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 involving string
2d3c0 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 s.** with embedd
2d3d0 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 ed NULs is undef
2d3e0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ined..**.** ^The
2d3f0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 fifth argument
2d400 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 to the BLOB and
2d410 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 string binding i
2d420 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 nterfaces.** is
2d430 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 a destructor use
2d440 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 d to dispose of
2d450 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 the BLOB or.** s
2d460 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 tring after SQLi
2d470 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 te has finished
2d480 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 with it. ^The d
2d490 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c estructor is cal
2d4a0 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 led.** to dispos
2d4b0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 e of the BLOB or
2d4c0 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 string even if
2d4d0 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 the call to bind
2d4e0 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e API fails..** ^
2d4f0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 If the fifth arg
2d500 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 ument is.** the
2d510 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 special value [S
2d520 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 QLITE_STATIC], t
2d530 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d hen SQLite assum
2d540 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 es that the.** i
2d550 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e nformation is in
2d560 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 static, unmanag
2d570 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 ed space and doe
2d580 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 s not need to be
2d590 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 freed..** ^If t
2d5a0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
2d5b0 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 t has the value
2d5c0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e [SQLITE_TRANSIEN
2d5d0 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 T], then.** SQLi
2d5e0 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e te makes its own
2d5f0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
2d600 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 the data immedi
2d610 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a ately, before.**
2d620 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
2d630 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 d_*() routine re
2d640 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 turns..**.** ^Th
2d650 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 e sixth argument
2d660 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2d670 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 _text64() must b
2d680 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c e one of.** [SQL
2d690 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 ITE_UTF8], [SQLI
2d6a0 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 TE_UTF16], [SQLI
2d6b0 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 TE_UTF16BE], or
2d6c0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d [SQLITE_UTF16LE]
2d6d0 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 .** to specify t
2d6e0 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 he encoding of t
2d6f0 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 he text in the t
2d700 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 hird parameter.
2d710 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 If.** the sixth
2d720 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
2d730 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 ite3_bind_text64
2d740 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 () is not one of
2d750 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 the.** allowed
2d760 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f values shown abo
2d770 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 ve, or if the te
2d780 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 xt encoding is d
2d790 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d ifferent.** from
2d7a0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 the encoding sp
2d7b0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73 ecified by the s
2d7c0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 ixth parameter,
2d7d0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
2d7e0 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 r.** is undefine
2d7f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
2d800 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 lite3_bind_zerob
2d810 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 lob() routine bi
2d820 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 nds a BLOB of le
2d830 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 ngth N that.** i
2d840 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 s filled with ze
2d850 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c roes. ^A zerobl
2d860 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 ob uses a fixed
2d870 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 amount of memory
2d880 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 .** (just an int
2d890 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 eger to hold its
2d8a0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 size) while it
2d8b0 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 is being process
2d8c0 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 ed..** Zeroblobs
2d8d0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f are intended to
2d8e0 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 serve as placeh
2d8f0 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 olders for BLOBs
2d900 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e whose.** conten
2d910 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 t is later writt
2d920 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c en using.** [sql
2d930 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c ite3_blob_open |
2d940 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f incremental BLO
2d950 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e B I/O] routines.
2d960 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 .** ^A negative
2d970 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 value for the ze
2d980 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 roblob results i
2d990 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 n a zero-length
2d9a0 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 BLOB..**.** ^If
2d9b0 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 any of the sqlit
2d9c0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
2d9d0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
2d9e0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
2d9f0 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b ter.** for the [
2da00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2da10 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 nt] or with a pr
2da20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2da30 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 for which.** [s
2da40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 qlite3_step()] h
2da50 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d as been called m
2da60 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 ore recently tha
2da70 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 n [sqlite3_reset
2da80 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ()],.** then the
2da90 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 call will retur
2daa0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 n [SQLITE_MISUSE
2dab0 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 ]. If any sqlit
2dac0 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f e3_bind_().** ro
2dad0 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 utine is passed
2dae0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2daf0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 ement] that has
2db00 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 been finalized,
2db10 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 the.** result is
2db20 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 undefined and p
2db30 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e robably harmful.
2db40 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 .**.** ^Bindings
2db50 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 are not cleared
2db60 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 by the [sqlite3
2db70 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e _reset()] routin
2db80 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 e..** ^Unbound p
2db90 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e arameters are in
2dba0 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c terpreted as NUL
2dbb0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 L..**.** ^The sq
2dbc0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 lite3_bind_* rou
2dbd0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 tines return [SQ
2dbe0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
2dbf0 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 ess or an.** [er
2dc00 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 ror code] if any
2dc10 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 thing goes wrong
2dc20 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f ..** ^[SQLITE_TO
2dc30 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 OBIG] might be r
2dc40 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 eturned if the s
2dc50 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 ize of a string
2dc60 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 or BLOB.** excee
2dc70 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 ds limits impose
2dc80 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 d by [sqlite3_li
2dc90 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d mit]([SQLITE_LIM
2dca0 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a IT_LENGTH]) or.*
2dcb0 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 * [SQLITE_MAX_LE
2dcc0 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 NGTH]..** ^[SQLI
2dcd0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 TE_RANGE] is ret
2dce0 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 urned if the par
2dcf0 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 ameter.** index
2dd00 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e is out of range.
2dd10 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ^[SQLITE_NOMEM
2dd20 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 ] is returned if
2dd30 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e malloc() fails.
2dd40 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2dd50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
2dd60 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 arameter_count()
2dd70 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
2dd80 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
2dd90 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 me()], and [sqli
2dda0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2ddb0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a er_index()]..*/.
2ddc0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
2ddd0 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 QLITE_APICALL sq
2dde0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
2ddf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2de00 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c nt, const void*,
2de10 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 53 51 4c int n, void(SQL
2de20 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 29 28 ITE_CALLBACK *)(
2de30 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f void*));.SQLITE_
2de40 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 API int SQLITE_A
2de50 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 PICALL sqlite3_b
2de60 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 ind_blob64(sqlit
2de70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
2de80 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 onst void*, sqli
2de90 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 te3_uint64,.
2dea0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2deb0 20 20 20 20 76 6f 69 64 28 53 51 4c 49 54 45 5f void(SQLITE_
2dec0 43 41 4c 4c 42 41 43 4b 20 2a 29 28 76 6f 69 64 CALLBACK *)(void
2ded0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 *));.SQLITE_API
2dee0 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 int SQLITE_APICA
2def0 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f LL sqlite3_bind_
2df00 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 double(sqlite3_s
2df10 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c tmt*, int, doubl
2df20 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 e);.SQLITE_API i
2df30 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c nt SQLITE_APICAL
2df40 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 L sqlite3_bind_i
2df50 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a nt(sqlite3_stmt*
2df60 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c , int, int);.SQL
2df70 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
2df80 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 TE_APICALL sqlit
2df90 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 e3_bind_int64(sq
2dfa0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2dfb0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 , sqlite3_int64)
2dfc0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2dfd0 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 SQLITE_APICALL
2dfe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c sqlite3_bind_nul
2dff0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c l(sqlite3_stmt*,
2e000 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
2e010 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 I int SQLITE_API
2e020 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e CALL sqlite3_bin
2e030 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 d_text(sqlite3_s
2e040 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 tmt*,int,const c
2e050 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 53 51 har*,int,void(SQ
2e060 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 29 LITE_CALLBACK *)
2e070 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 (void*));.SQLITE
2e080 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
2e090 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f APICALL sqlite3_
2e0a0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 bind_text16(sqli
2e0b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2e0c0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
2e0d0 2c 20 76 6f 69 64 28 53 51 4c 49 54 45 5f 43 41 , void(SQLITE_CA
2e0e0 4c 4c 42 41 43 4b 20 2a 29 28 76 6f 69 64 2a 29 LLBACK *)(void*)
2e0f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2e100 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c t SQLITE_APICALL
2e110 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
2e120 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d xt64(sqlite3_stm
2e130 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 t*, int, const c
2e140 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 har*, sqlite3_ui
2e150 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 nt64,.
2e160 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
2e170 6f 69 64 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 oid(SQLITE_CALLB
2e180 41 43 4b 20 2a 29 28 76 6f 69 64 2a 29 2c 20 75 ACK *)(void*), u
2e190 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 nsigned char enc
2e1a0 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 oding);.SQLITE_A
2e1b0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 PI int SQLITE_AP
2e1c0 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 ICALL sqlite3_bi
2e1d0 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 nd_value(sqlite3
2e1e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
2e1f0 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 st sqlite3_value
2e200 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
2e210 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c nt SQLITE_APICAL
2e220 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a L sqlite3_bind_z
2e230 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f eroblob(sqlite3_
2e240 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 stmt*, int, int
2e250 6e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 n);.SQLITE_API i
2e260 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c nt SQLITE_APICAL
2e270 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a L sqlite3_bind_z
2e280 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 eroblob64(sqlite
2e290 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 3_stmt*, int, sq
2e2a0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a lite3_uint64);..
2e2b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2e2c0 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 Number Of SQL Pa
2e2d0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 rameters.** METH
2e2e0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2e2f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
2e300 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 tine can be used
2e310 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d to find the num
2e320 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 ber of [SQL para
2e330 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 meters].** in a
2e340 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2e350 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d ent]. SQL param
2e360 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 eters are tokens
2e370 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 of the.** form
2e380 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 "?", "?NNN", ":A
2e390 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 AA", "$AAA", or
2e3a0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 "@AAA" that serv
2e3b0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c e as.** placehol
2e3c0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 ders for values
2e3d0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 that are [sqlite
2e3e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 3_bind_blob | bo
2e3f0 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 und].** to the p
2e400 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c arameters at a l
2e410 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a ater time..**.**
2e420 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ^(This routine
2e430 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 actually returns
2e440 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 the index of th
2e450 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 e largest (right
2e460 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 most).** paramet
2e470 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d er. For all form
2e480 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 s except ?NNN, t
2e490 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 his will corresp
2e4a0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 ond to the.** nu
2e4b0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 mber of unique p
2e4c0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 arameters. If p
2e4d0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
2e4e0 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 ?NNN form are u
2e4f0 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 sed,.** there ma
2e500 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 y be gaps in the
2e510 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 list.)^.**.** S
2e520 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
2e530 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
2e540 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
2e550 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2e560 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c rameter_name()],
2e570 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
2e580 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2e590 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c index()]..*/.SQL
2e5a0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
2e5b0 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 TE_APICALL sqlit
2e5c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2e5d0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f r_count(sqlite3_
2e5e0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
2e5f0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 API3REF: Name Of
2e600 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 A Host Paramete
2e610 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c r.** METHOD: sql
2e620 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2e630 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
2e640 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
2e650 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 (P,N) interface
2e660 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
2e670 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 ame of the N-th
2e680 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 [SQL parameter]
2e690 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 in the [prepared
2e6a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a statement] P..*
2e6b0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 * ^(SQL paramete
2e6c0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 rs of the form "
2e6d0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 ?NNN" or ":AAA"
2e6e0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 or "@AAA" or "$A
2e6f0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 AA".** have a na
2e700 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 me which is the
2e710 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 string "?NNN" or
2e720 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 ":AAA" or "@AAA
2e730 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 " or "$AAA".** r
2e740 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
2e750 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
2e760 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 the initial ":"
2e770 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 or "$" or "@" or
2e780 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 "?".** is inclu
2e790 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 ded as part of t
2e7a0 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 he name.)^.** ^P
2e7b0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
2e7c0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 form "?" withou
2e7d0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e t a following in
2e7e0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 teger have no na
2e7f0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 me.** and are re
2e800 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 ferred to as "na
2e810 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e meless" or "anon
2e820 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 ymous parameters
2e830 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 "..**.** ^The fi
2e840 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 rst host paramet
2e850 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 er has an index
2e860 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a of 1, not 0..**.
2e870 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 ** ^If the value
2e880 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e N is out of ran
2e890 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 ge or if the N-t
2e8a0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
2e8b0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e * nameless, then
2e8c0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 NULL is returne
2e8d0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 d. ^The returne
2e8e0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 d string is.** a
2e8f0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 lways in UTF-8 e
2e900 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 ncoding even if
2e910 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 the named parame
2e920 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 ter was.** origi
2e930 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 nally specified
2e940 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 as UTF-16 in [sq
2e950 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
2e960 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
2e970 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
2e980 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 ]..**.** See als
2e990 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
2e9a0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
2e9b0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
2e9c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2e9d0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a r_count()], and.
2e9e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
2e9f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
2ea00 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
2ea10 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 PI const char *S
2ea20 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 QLITE_APICALL sq
2ea30 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2ea40 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 eter_name(sqlite
2ea50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 3_stmt*, int);..
2ea60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2ea70 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d Index Of A Param
2ea80 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 eter With A Give
2ea90 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 n Name.** METHOD
2eaa0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
2eab0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 *.** ^Return the
2eac0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c index of an SQL
2ead0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e parameter given
2eae0 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 its name. ^The
2eaf0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 .** index value
2eb00 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 returned is suit
2eb10 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 able for use as
2eb20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 the second.** pa
2eb30 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
2eb40 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
2eb50 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 lite3_bind()].
2eb60 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 ^A zero.** is re
2eb70 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 turned if no mat
2eb80 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 ching parameter
2eb90 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 is found. ^The
2eba0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d parameter.** nam
2ebb0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 e must be given
2ebc0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 in UTF-8 even if
2ebd0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 the original st
2ebe0 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 atement.** was p
2ebf0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 repared from UTF
2ec00 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b -16 text using [
2ec10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2ec20 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v2()]..**.** S
2ec30 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
2ec40 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
2ec50 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
2ec60 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2ec70 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
2ec80 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
2ec90 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2eca0 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c _name()]..*/.SQL
2ecb0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
2ecc0 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 TE_APICALL sqlit
2ecd0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2ece0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f r_index(sqlite3_
2ecf0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 stmt*, const cha
2ed00 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a r *zName);../*.*
2ed10 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
2ed20 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f t All Bindings O
2ed30 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 n A Prepared Sta
2ed40 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 tement.** METHOD
2ed50 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
2ed60 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 *.** ^Contrary t
2ed70 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 o the intuition
2ed80 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 of many, [sqlite
2ed90 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 3_reset()] does
2eda0 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 not reset.** the
2edb0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2edc0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 lob | bindings]
2edd0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 on a [prepared s
2ede0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 tatement]..** ^U
2edf0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 se this routine
2ee00 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 to reset all hos
2ee10 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 t parameters to
2ee20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f NULL..*/.SQLITE_
2ee30 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 API int SQLITE_A
2ee40 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 PICALL sqlite3_c
2ee50 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 lear_bindings(sq
2ee60 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
2ee70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
2ee80 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 umber Of Columns
2ee90 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 In A Result Set
2eea0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
2eeb0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
2eec0 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 Return the numbe
2eed0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
2eee0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 the result set r
2eef0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a eturned by the.*
2ef00 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
2ef10 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f ement]. ^This ro
2ef20 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 utine returns 0
2ef30 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 if pStmt is an S
2ef40 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 QL.** statement
2ef50 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 that does not re
2ef60 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 turn data (for e
2ef70 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 xample an [UPDAT
2ef80 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 E])..**.** See a
2ef90 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 lso: [sqlite3_da
2efa0 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 ta_count()].*/.S
2efb0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2efc0 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c LITE_APICALL sql
2efd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e ite3_column_coun
2efe0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
2eff0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
2f000 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 API3REF: Column
2f010 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c Names In A Resul
2f020 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a t Set.** METHOD:
2f030 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2f040 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
2f050 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e nes return the n
2f060 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 ame assigned to
2f070 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c a particular col
2f080 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 umn.** in the re
2f090 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 sult set of a [S
2f0a0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
2f0b0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
2f0c0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a column_name().**
2f0d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2f0e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
2f0f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
2f100 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a d UTF-8 string.*
2f110 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f * and sqlite3_co
2f120 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 lumn_name16() re
2f130 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
2f140 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
2f150 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 ated.** UTF-16 s
2f160 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 tring. ^The fir
2f170 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
2f180 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
2f190 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 atement].** that
2f1a0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 implements the
2f1b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
2f1c0 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 nt. ^The second
2f1d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
2f1e0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 .** column numbe
2f1f0 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 r. ^The leftmos
2f200 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 t column is numb
2f210 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 er 0..**.** ^The
2f220 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
2f230 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 pointer is vali
2f240 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 d until either t
2f250 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2f260 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 tement].** is de
2f270 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 stroyed by [sqli
2f280 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2f290 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 or until the sta
2f2a0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 tement is automa
2f2b0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 tically.** repre
2f2c0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 pared by the fir
2f2d0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 st call to [sqli
2f2e0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 te3_step()] for
2f2f0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e a particular run
2f300 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 .** or until the
2f310 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a next call to.**
2f320 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2f330 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 name() or sqlite
2f340 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 3_column_name16(
2f350 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f ) on the same co
2f360 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 lumn..**.** ^If
2f370 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
2f380 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 fails during th
2f390 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 e processing of
2f3a0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a either routine.*
2f3b0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 * (for example d
2f3c0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 uring a conversi
2f3d0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f on from UTF-8 to
2f3e0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a UTF-16) then a.
2f3f0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 ** NULL pointer
2f400 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
2f410 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 ** ^The name of
2f420 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 a result column
2f430 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 is the value of
2f440 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 the "AS" clause
2f450 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 for.** that colu
2f460 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 mn, if there is
2f470 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 an AS clause. I
2f480 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 f there is no AS
2f490 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 clause.** then
2f4a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
2f4b0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 column is unspec
2f4c0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 ified and may ch
2f4d0 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 ange from.** one
2f4e0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
2f4f0 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a te to the next..
2f500 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
2f510 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 nst char *SQLITE
2f520 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 _APICALL sqlite3
2f530 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c _column_name(sql
2f540 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
2f550 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 N);.SQLITE_API c
2f560 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 onst void *SQLIT
2f570 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 E_APICALL sqlite
2f580 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 3_column_name16(
2f590 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2f5a0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt N);../*.** CA
2f5b0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f PI3REF: Source O
2f5c0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 f Data In A Quer
2f5d0 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 y Result.** METH
2f5e0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2f5f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
2f600 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 utines provide a
2f610 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d means to determ
2f620 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ine the database
2f630 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 , table, and.**
2f640 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 table column tha
2f650 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 t is the origin
2f660 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 of a particular
2f670 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e result column in
2f680 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 .** [SELECT] sta
2f690 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 tement..** ^The
2f6a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
2f6b0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 base or table or
2f6c0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 column can be r
2f6d0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 eturned as.** ei
2f6e0 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 ther a UTF-8 or
2f6f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 UTF-16 string.
2f700 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 ^The _database_
2f710 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a routines return.
2f720 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
2f730 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 name, the _table
2f740 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 _ routines retur
2f750 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 n the table name
2f760 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 , and.** the ori
2f770 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 gin_ routines re
2f780 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 turn the column
2f790 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 name..** ^The re
2f7a0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 turned string is
2f7b0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 valid until the
2f7c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2f7d0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 ment] is destroy
2f7e0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c ed.** using [sql
2f7f0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
2f800 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 or until the st
2f810 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d atement is autom
2f820 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 atically.** repr
2f830 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 epared by the fi
2f840 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c rst call to [sql
2f850 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 ite3_step()] for
2f860 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 a particular ru
2f870 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 n.** or until th
2f880 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 e same informati
2f890 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a on is requested.
2f8a0 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 ** again in a di
2f8b0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 fferent encoding
2f8c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d ..**.** ^The nam
2f8d0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 es returned are
2f8e0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d the original un-
2f8f0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 aliased names of
2f900 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
2f910 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c , table, and col
2f920 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 umn..**.** ^The
2f930 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
2f940 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 o these interfac
2f950 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 es is a [prepare
2f960 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
2f970 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e ^These function
2f980 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 s return informa
2f990 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e tion about the N
2f9a0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e th result column
2f9b0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
2f9c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 the statement, w
2f9d0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 here N is the se
2f9e0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 cond function ar
2f9f0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 gument..** ^The
2fa00 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e left-most column
2fa10 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 is column 0 for
2fa20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
2fa30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e .**.** ^If the N
2fa40 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e th column return
2fa50 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d ed by the statem
2fa60 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 ent is an expres
2fa70 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 sion or.** subqu
2fa80 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 ery and is not a
2fa90 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 column value, t
2faa0 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 hen all of these
2fab0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
2fac0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 n.** NULL. ^The
2fad0 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 se routine might
2fae0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c also return NUL
2faf0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c L if a memory al
2fb00 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a location error.*
2fb10 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 * occurs. ^Othe
2fb20 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 rwise, they retu
2fb30 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 rn the name of t
2fb40 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 he attached data
2fb50 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 base, table,.**
2fb60 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 or column that q
2fb70 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 uery result colu
2fb80 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 mn was extracted
2fb90 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 from..**.** ^As
2fba0 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 with all other
2fbb0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f SQLite APIs, tho
2fbc0 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 se whose names e
2fbd0 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 nd with "16" ret
2fbe0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e urn.** UTF-16 en
2fbf0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e coded strings an
2fc00 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 d the other func
2fc10 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 tions return UTF
2fc20 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 -8..**.** ^These
2fc30 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 APIs are only a
2fc40 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 vailable if the
2fc50 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 library was comp
2fc60 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a iled with the.**
2fc70 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
2fc80 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d COLUMN_METADATA]
2fc90 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C-preprocessor
2fca0 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 symbol..**.** If
2fcb0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 two or more thr
2fcc0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 eads call one or
2fcd0 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 more of these r
2fce0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 outines against
2fcf0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 the same.** prep
2fd00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 ared statement a
2fd10 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 nd column at the
2fd20 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 same time then
2fd30 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a the results are.
2fd40 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a ** undefined..**
2fd50 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f .** If two or mo
2fd60 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 re threads call
2fd70 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b one or more.** [
2fd80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
2fd90 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 atabase_name | c
2fda0 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 olumn metadata i
2fdb0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f nterfaces].** fo
2fdc0 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 r the same [prep
2fdd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2fde0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d and result colum
2fdf0 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 n.** at the same
2fe00 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 time then the r
2fe10 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 esults are undef
2fe20 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ined..*/.SQLITE_
2fe30 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
2fe40 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 SQLITE_APICALL s
2fe50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
2fe60 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 tabase_name(sqli
2fe70 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
2fe80 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2fe90 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 41 50 void *SQLITE_AP
2fea0 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f ICALL sqlite3_co
2feb0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
2fec0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
2fed0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f t*,int);.SQLITE_
2fee0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
2fef0 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 SQLITE_APICALL s
2ff00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 qlite3_column_ta
2ff10 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ble_name(sqlite3
2ff20 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c _stmt*,int);.SQL
2ff30 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
2ff40 69 64 20 2a 53 51 4c 49 54 45 5f 41 50 49 43 41 id *SQLITE_APICA
2ff50 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
2ff60 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 n_table_name16(s
2ff70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2ff80 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
2ff90 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 nst char *SQLITE
2ffa0 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 _APICALL sqlite3
2ffb0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e _column_origin_n
2ffc0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
2ffd0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 *,int);.SQLITE_A
2ffe0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 PI const void *S
2fff0 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 QLITE_APICALL sq
30000 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 lite3_column_ori
30010 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 gin_name16(sqlit
30020 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a e3_stmt*,int);..
30030 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
30040 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 Declared Datatyp
30050 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 e Of A Query Res
30060 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ult.** METHOD: s
30070 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
30080 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 * ^(The first pa
30090 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 rameter is a [pr
300a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
300b0 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 ]..** If this st
300c0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 atement is a [SE
300d0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 LECT] statement
300e0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 and the Nth colu
300f0 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 mn of the.** ret
30100 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 urned result set
30110 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 of that [SELECT
30120 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c ] is a table col
30130 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 umn (not an.** e
30140 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 xpression or sub
30150 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 query) then the
30160 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 declared type of
30170 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f the table.** co
30180 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 lumn is returned
30190 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 .)^ ^If the Nth
301a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
301b0 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a esult set is an.
301c0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 ** expression or
301d0 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 subquery, then
301e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
301f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e s returned..** ^
30200 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
30210 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 ing is always UT
30220 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a F-8 encoded..**.
30230 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 ** ^(For example
30240 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 , given the data
30250 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a base schema:.**.
30260 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 ** CREATE TABLE
30270 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a t1(c1 VARIANT);.
30280 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f **.** and the fo
30290 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e llowing statemen
302a0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
302b0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 :.**.** SELECT c
302c0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 1 + 1, c1 FROM t
302d0 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 1;.**.** this ro
302e0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 utine would retu
302f0 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 rn the string "V
30300 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 ARIANT" for the
30310 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a second result.**
30320 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 column (i==1),
30330 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 and a NULL point
30340 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 er for the first
30350 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 result column (
30360 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e i==0).)^.**.** ^
30370 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 SQLite uses dyna
30380 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 mic run-time typ
30390 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 ing. ^So just b
303a0 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a ecause a column.
303b0 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 ** is declared t
303c0 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 o contain a part
303d0 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 icular type does
303e0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 not mean that t
303f0 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 he.** data store
30400 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e d in that column
30410 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 is of the decla
30420 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 red type. SQLit
30430 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 e is.** strongly
30440 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 typed, but the
30450 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 typing is dynami
30460 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e c not static. ^
30470 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 Type.** is assoc
30480 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 iated with indiv
30490 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f idual values, no
304a0 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 t with the conta
304b0 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f iners.** used to
304c0 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 hold those valu
304d0 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 es..*/.SQLITE_AP
304e0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 I const char *SQ
304f0 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c LITE_APICALL sql
30500 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c ite3_column_decl
30510 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d type(sqlite3_stm
30520 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f t*,int);.SQLITE_
30530 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
30540 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 SQLITE_APICALL s
30550 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 qlite3_column_de
30560 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 cltype16(sqlite3
30570 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a _stmt*,int);../*
30580 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 .** CAPI3REF: Ev
30590 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 aluate An SQL St
305a0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f atement.** METHO
305b0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
305c0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 **.** After a [p
305d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
305e0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 t] has been prep
305f0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 ared using eithe
30600 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 r.** [sqlite3_pr
30610 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b epare_v2()] or [
30620 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
30630 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 6_v2()] or one o
30640 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 f the legacy.**
30650 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 interfaces [sqli
30660 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
30670 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
30680 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 re16()], this fu
30690 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 nction.** must b
306a0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 e called one or
306b0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 more times to ev
306c0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 aluate the state
306d0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ment..**.** The
306e0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 details of the b
306f0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 ehavior of the s
30700 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e qlite3_step() in
30710 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a terface depend.*
30720 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 * on whether the
30730 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 statement was p
30740 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 repared using th
30750 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 e newer "v2" int
30760 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 erface.** [sqlit
30770 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
30780 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
30790 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 epare16_v2()] or
307a0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 the older legac
307b0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b y.** interface [
307c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
307d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
307e0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 prepare16()]. T
307f0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a he use of the.**
30800 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 new "v2" interf
30810 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 ace is recommend
30820 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 ed for new appli
30830 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 cations but the
30840 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 legacy.** interf
30850 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 ace will continu
30860 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 e to be supporte
30870 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 d..**.** ^In the
30880 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
30890 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 e, the return va
308a0 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 lue will be eith
308b0 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d er [SQLITE_BUSY]
308c0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e ,.** [SQLITE_DON
308d0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d E], [SQLITE_ROW]
308e0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d , [SQLITE_ERROR]
308f0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 , or [SQLITE_MIS
30900 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 USE]..** ^With t
30910 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
30920 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 e, any of the ot
30930 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 her [result code
30940 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 s] or.** [extend
30950 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d ed result codes]
30960 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e might be return
30970 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a ed as well..**.*
30980 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d * ^[SQLITE_BUSY]
30990 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
309a0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 database engine
309b0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 was unable to ac
309c0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 quire the.** dat
309d0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e abase locks it n
309e0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a eeds to do its j
309f0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 ob. ^If the sta
30a00 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d tement is a [COM
30a10 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 MIT].** or occur
30a20 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 s outside of an
30a30 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 explicit transac
30a40 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 tion, then you c
30a50 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 an retry the.**
30a60 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 statement. If t
30a70 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
30a80 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 not a [COMMIT] a
30a90 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e nd occurs within
30aa0 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 an.** explicit
30ab0 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e transaction then
30ac0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c you should roll
30ad0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 back the transac
30ae0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 tion before.** c
30af0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a ontinuing..**.**
30b00 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 ^[SQLITE_DONE]
30b10 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 means that the s
30b20 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e tatement has fin
30b30 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a ished executing.
30b40 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e ** successfully.
30b50 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 sqlite3_step()
30b60 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 should not be c
30b70 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 alled again on t
30b80 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d his virtual.** m
30b90 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 achine without f
30ba0 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 irst calling [sq
30bb0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 lite3_reset()] t
30bc0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 o reset the virt
30bd0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 ual.** machine b
30be0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 ack to its initi
30bf0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 al state..**.**
30c00 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 ^If the SQL stat
30c10 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 ement being exec
30c20 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 uted returns any
30c30 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c data, then [SQL
30c40 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 ITE_ROW].** is r
30c50 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d eturned each tim
30c60 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 e a new row of d
30c70 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 ata is ready for
30c80 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 processing by t
30c90 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 he.** caller. Th
30ca0 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 e values may be
30cb0 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 accessed using t
30cc0 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 he [column acces
30cd0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a s functions]..**
30ce0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
30cf0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 is called again
30d00 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 to retrieve the
30d10 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 next row of data
30d20 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 ..**.** ^[SQLITE
30d30 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 _ERROR] means th
30d40 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 at a run-time er
30d50 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 ror (such as a c
30d60 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f onstraint.** vio
30d70 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 lation) has occu
30d80 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 rred. sqlite3_s
30d90 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 tep() should not
30da0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e be called again
30db0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d on.** the VM. M
30dc0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ore information
30dd0 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 may be found by
30de0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
30df0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e _errmsg()]..** ^
30e00 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 With the legacy
30e10 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 interface, a mor
30e20 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 e specific error
30e30 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 code (for examp
30e40 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 le,.** [SQLITE_I
30e50 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 NTERRUPT], [SQLI
30e60 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c TE_SCHEMA], [SQL
30e70 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e ITE_CORRUPT], an
30e80 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 d so forth).** c
30e90 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 an be obtained b
30ea0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
30eb0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 e3_reset()] on t
30ec0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
30ed0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e statement]. ^In
30ee0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
30ef0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 ace,.** the more
30f00 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
30f10 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 code is returned
30f20 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c directly by sql
30f30 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a ite3_step()..**.
30f40 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 ** [SQLITE_MISUS
30f50 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 E] means that th
30f60 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 e this routine w
30f70 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 as called inappr
30f80 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 opriately..** Pe
30f90 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c rhaps it was cal
30fa0 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 led on a [prepar
30fb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
30fc0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 at has.** alread
30fd0 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f y been [sqlite3_
30fe0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c finalize | final
30ff0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 ized] or on one
31000 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 that had.** prev
31010 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 iously returned
31020 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f [SQLITE_ERROR] o
31030 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e r [SQLITE_DONE].
31040 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a Or it could.**
31050 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 be the case tha
31060 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 t the same datab
31070 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
31080 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 s being used by
31090 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 two or.** more t
310a0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 hreads at the sa
310b0 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d me moment in tim
310c0 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c e..**.** For all
310d0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
310e0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e ite up to and in
310f0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 cluding 3.6.23.1
31100 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b , a call to.** [
31110 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
31120 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 was required af
31130 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 ter sqlite3_step
31140 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 () returned anyt
31150 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 hing.** other th
31160 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 an [SQLITE_ROW]
31170 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 before any subse
31180 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e quent invocation
31190 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 of.** sqlite3_s
311a0 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 tep(). Failure
311b0 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 to reset the pre
311c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
311d0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 using .** [sqlit
311e0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c e3_reset()] woul
311f0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b d result in an [
31200 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 SQLITE_MISUSE] r
31210 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 eturn from.** sq
31220 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 lite3_step(). B
31230 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e ut after version
31240 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 3.6.23.1, sqlit
31250 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a e3_step() began.
31260 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 ** calling [sqli
31270 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 te3_reset()] aut
31280 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 omatically in th
31290 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 is circumstance
312a0 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 rather.** than r
312b0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 eturning [SQLITE
312c0 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 _MISUSE]. This
312d0 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 is not considere
312e0 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 d a compatibilit
312f0 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 y.** break becau
31300 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 se any applicati
31310 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 on that ever rec
31320 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f eives an SQLITE_
31330 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 MISUSE error.**
31340 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 is broken by def
31350 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 inition. The [S
31360 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 QLITE_OMIT_AUTOR
31370 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 ESET] compile-ti
31380 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e me option.** can
31390 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 be used to rest
313a0 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 ore the legacy b
313b0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c ehavior..**.** <
313c0 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 b>Goofy Interfac
313d0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 e Alert:</b> In
313e0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 the legacy inter
313f0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 face, the sqlite
31400 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 3_step().** API
31410 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 always returns a
31420 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 generic error c
31430 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 ode, [SQLITE_ERR
31440 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 OR], following a
31450 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 ny.** error othe
31460 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 r than [SQLITE_B
31470 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 USY] and [SQLITE
31480 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d _MISUSE]. You m
31490 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c ust call.** [sql
314a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
314b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
314c0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 ze()] in order t
314d0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 o find one of th
314e0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 e.** specific [e
314f0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 rror codes] that
31500 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 better describe
31510 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 s the error..**
31520 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 We admit that th
31530 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 is is a goofy de
31540 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c sign. The probl
31550 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 em has been fixe
31560 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 d.** with the "v
31570 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 2" interface. I
31580 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c f you prepare al
31590 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 l of your SQL st
315a0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e atements.** usin
315b0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 g either [sqlite
315c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
315d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
315e0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 are16_v2()] inst
315f0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 ead.** of the le
31600 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 gacy [sqlite3_pr
31610 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 epare()] and [sq
31620 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
31630 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a )] interfaces,.*
31640 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 * then the more
31650 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 specific [error
31660 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 codes] are retur
31670 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 ned directly.**
31680 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 by sqlite3_step(
31690 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 ). The use of t
316a0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
316b0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 e is recommended
316c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
316d0 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 int SQLITE_APICA
316e0 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 LL sqlite3_step(
316f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
31700 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
31710 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d Number of colum
31720 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 ns in a result s
31730 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 et.** METHOD: sq
31740 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
31750 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 ^The sqlite3_da
31760 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 ta_count(P) inte
31770 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
31780 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
31790 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 mns in the.** cu
317a0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 rrent row of the
317b0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b result set of [
317c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
317d0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 nt] P..** ^If pr
317e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
317f0 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 P does not have
31800 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 results ready t
31810 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 o return.** (via
31820 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 calls to the [s
31830 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
31840 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 t | sqlite3_colu
31850 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e mn_*()] of.** in
31860 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 terfaces) then s
31870 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
31880 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a t(P) returns 0..
31890 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
318a0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f data_count(P) ro
318b0 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 utine also retur
318c0 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e ns 0 if P is a N
318d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 ULL pointer..**
318e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
318f0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 a_count(P) routi
31900 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 ne returns 0 if
31910 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c the previous cal
31920 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
31930 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e _step](P) return
31940 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ed [SQLITE_DONE]
31950 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
31960 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a data_count(P).**
31970 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e will return non
31980 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 -zero if previou
31990 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 s call to [sqlit
319a0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 e3_step](P) retu
319b0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f rned.** [SQLITE_
319c0 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 ROW], except in
319d0 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 the case of the
319e0 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e [PRAGMA incremen
319f0 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 tal_vacuum].** w
31a00 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 here it always r
31a10 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 eturns zero sinc
31a20 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 e each step of t
31a30 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a hat multi-step.*
31a40 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 * pragma returns
31a50 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 0 columns of da
31a60 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ta..**.** See al
31a70 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c so: [sqlite3_col
31a80 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a umn_count()].*/.
31a90 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
31aa0 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 QLITE_APICALL sq
31ab0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
31ac0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
31ad0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
31ae0 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e PI3REF: Fundamen
31af0 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a tal Datatypes.**
31b00 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 KEYWORDS: SQLIT
31b10 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 E_TEXT.**.** ^(E
31b20 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 very value in SQ
31b30 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 Lite has one of
31b40 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c five fundamental
31b50 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a datatypes:.**.*
31b60 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 * <ul>.** <li> 6
31b70 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 4-bit signed int
31b80 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d eger.** <li> 64-
31b90 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e bit IEEE floatin
31ba0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a g point number.*
31bb0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a * <li> string.**
31bc0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c <li> BLOB.** <l
31bd0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e i> NULL.** </ul>
31be0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 )^.**.** These c
31bf0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 onstants are cod
31c00 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 es for each of t
31c10 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a hose types..**.*
31c20 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 * Note that the
31c30 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 SQLITE_TEXT cons
31c40 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 tant was also us
31c50 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 ed in SQLite ver
31c60 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 sion 2.** for a
31c70 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 completely diffe
31c80 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 rent meaning. S
31c90 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e oftware that lin
31ca0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a ks against both.
31cb0 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f ** SQLite versio
31cc0 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 n 2 and SQLite v
31cd0 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 ersion 3 should
31ce0 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 use SQLITE3_TEXT
31cf0 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f , not.** SQLITE_
31d00 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 TEXT..*/.#define
31d10 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 SQLITE_INTEGER
31d20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
31d30 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 E_FLOAT 2.#de
31d40 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 fine SQLITE_BLOB
31d50 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 4.#define S
31d60 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 QLITE_NULL 5
31d70 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 .#ifdef SQLITE_T
31d80 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 EXT.# undef SQLI
31d90 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 TE_TEXT.#else.#
31da0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
31db0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a XT 3.#endif.
31dc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f #define SQLITE3_
31dd0 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a TEXT 3../*.*
31de0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 * CAPI3REF: Resu
31df0 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 lt Values From A
31e00 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 Query.** KEYWOR
31e10 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 DS: {column acce
31e20 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a ss functions}.**
31e30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
31e40 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _stmt.**.** ^The
31e50 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
31e60 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 rn information a
31e70 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f bout a single co
31e80 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 lumn of the curr
31e90 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f ent.** result ro
31ea0 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e w of a query. ^
31eb0 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 In every case th
31ec0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
31ed0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a is a pointer.**
31ee0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 to the [prepare
31ef0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
31f00 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 t is being evalu
31f10 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 ated (the [sqlit
31f20 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 e3_stmt*].** tha
31f30 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 t was returned f
31f40 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 rom [sqlite3_pre
31f50 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e pare_v2()] or on
31f60 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 e of its variant
31f70 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 s).** and the se
31f80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
31f90 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 the index of th
31fa0 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 e column for whi
31fb0 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a ch information.*
31fc0 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 * should be retu
31fd0 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d rned. ^The leftm
31fe0 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 ost column of th
31ff0 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 e result set has
32000 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a the index 0..**
32010 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 ^The number of
32020 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
32030 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 esult can be det
32040 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a ermined using.**
32050 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
32060 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a _count()]..**.**
32070 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 If the SQL stat
32080 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 ement does not c
32090 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 urrently point t
320a0 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f o a valid row, o
320b0 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 r if the.** colu
320c0 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 mn index is out
320d0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 of range, the re
320e0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 sult is undefine
320f0 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 d..** These rout
32100 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 ines may only be
32110 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 called when the
32120 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c most recent cal
32130 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
32140 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 _step()] has ret
32150 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f urned [SQLITE_RO
32160 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a W] and neither.*
32170 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
32180 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 ()] nor [sqlite3
32190 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 _finalize()] hav
321a0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 e been called su
321b0 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 bsequently..** I
321c0 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 f any of these r
321d0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c outines are call
321e0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 ed after [sqlite
321f0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 3_reset()] or.**
32200 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
32210 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b ze()] or after [
32220 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
32230 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 has returned.**
32240 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 something other
32250 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 than [SQLITE_ROW
32260 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 ], the results a
32270 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a re undefined..**
32280 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 If [sqlite3_ste
32290 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 p()] or [sqlite3
322a0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 _reset()] or [sq
322b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
322c0 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 ].** are called
322d0 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 from a different
322e0 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e thread while an
322f0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 y of these routi
32300 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 nes.** are pendi
32310 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 ng, then the res
32320 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
32330 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
32340 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
32350 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 pe() routine ret
32360 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c urns the.** [SQL
32370 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 ITE_INTEGER | da
32380 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 tatype code] for
32390 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 the initial dat
323a0 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 a type.** of the
323b0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 result column.
323c0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 ^The returned v
323d0 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b alue is one of [
323e0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c SQLITE_INTEGER],
323f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 .** [SQLITE_FLOA
32400 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 T], [SQLITE_TEXT
32410 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d ], [SQLITE_BLOB]
32420 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c , or [SQLITE_NUL
32430 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a L]. The value.*
32440 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 * returned by sq
32450 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
32460 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e e() is only mean
32470 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 ingful if no typ
32480 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 e.** conversions
32490 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 have occurred a
324a0 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f s described belo
324b0 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 w. After a type
324c0 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 conversion,.**
324d0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
324e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
324f0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 lumn_type() is u
32500 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 ndefined. Futur
32510 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 e.** versions of
32520 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e SQLite may chan
32530 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 ge the behavior
32540 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d of sqlite3_colum
32550 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c n_type().** foll
32560 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e owing a type con
32570 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e version..**.** ^
32580 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
32590 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 a BLOB or UTF-8
325a0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 string then the
325b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
325c0 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 bytes().** routi
325d0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ne returns the n
325e0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
325f0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 n that BLOB or s
32600 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
32610 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 e result is a UT
32620 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 F-16 string, the
32630 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
32640 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 _bytes() convert
32650 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 s.** the string
32660 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 to UTF-8 and the
32670 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
32680 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a mber of bytes..*
32690 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
326a0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 is a numeric va
326b0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 lue then sqlite3
326c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
326d0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 uses.** [sqlite3
326e0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 _snprintf()] to
326f0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c convert that val
32700 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 ue to a UTF-8 st
32710 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 ring and returns
32720 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
32730 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
32740 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
32750 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c he result is NUL
32760 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f L, then sqlite3_
32770 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 column_bytes() r
32780 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a eturns zero..**.
32790 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
327a0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 t is a BLOB or U
327b0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 TF-16 string the
327c0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f n the sqlite3_co
327d0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a lumn_bytes16().*
327e0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e * routine return
327f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
32800 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c bytes in that BL
32810 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a OB or string..**
32820 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
32830 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e is a UTF-8 strin
32840 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f g, then sqlite3_
32850 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
32860 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 converts.** the
32870 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 string to UTF-1
32880 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6 and then retur
32890 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
328a0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 bytes..** ^If t
328b0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e he result is a n
328c0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 umeric value the
328d0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
328e0 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a _bytes16() uses.
328f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 ** [sqlite3_snpr
32900 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 intf()] to conve
32910 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f rt that value to
32920 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 a UTF-16 string
32930 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 and returns.**
32940 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
32950 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 tes in that stri
32960 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 ng..** ^If the r
32970 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 esult is NULL, t
32980 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
32990 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 mn_bytes16() ret
329a0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a urns zero..**.**
329b0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 ^The values ret
329c0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
329d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
329e0 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 ] and .** [sqlit
329f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
32a00 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 6()] do not incl
32a10 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 ude the zero ter
32a20 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 minators at the
32a30 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 end.** of the st
32a40 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 ring. ^For clar
32a50 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 ity: the values
32a60 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
32a70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
32a80 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c ytes()] and [sql
32a90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
32aa0 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e s16()] are the n
32ab0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 umber of.** byte
32ac0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c s in the string,
32ad0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 not the number
32ae0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a of characters..*
32af0 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 *.** ^Strings re
32b00 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
32b10 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
32b20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
32b30 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 mn_text16(),.**
32b40 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e even empty strin
32b50 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a gs, are always z
32b60 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 ero-terminated.
32b70 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 ^The return.**
32b80 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 value from sqlit
32b90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
32ba0 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 for a zero-leng
32bb0 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c th BLOB is a NUL
32bc0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
32bd0 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e <b>Warning:</b>
32be0 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 ^The object ret
32bf0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
32c00 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 3_column_value()
32c10 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 ] is an.** [unpr
32c20 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
32c30 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 value] object.
32c40 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 In a multithread
32c50 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a ed environment,.
32c60 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 ** an unprotecte
32c70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
32c80 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 object may only
32c90 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 be used safely w
32ca0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ith.** [sqlite3_
32cb0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e bind_value()] an
32cc0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c d [sqlite3_resul
32cd0 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 t_value()]..** I
32ce0 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 f the [unprotect
32cf0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
32d00 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 ] object returne
32d10 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
32d20 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
32d30 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 is used in any
32d40 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 other way, inclu
32d50 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f ding calls.** to
32d60 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b routines like [
32d70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e sqlite3_value_in
32d80 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 t()], [sqlite3_v
32d90 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a alue_text()],.**
32da0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c or [sqlite3_val
32db0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 ue_bytes()], the
32dc0 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 behavior is not
32dd0 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a threadsafe..**.
32de0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
32df0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e s attempt to con
32e00 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 vert the value w
32e10 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 here appropriate
32e20 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 . ^For.** examp
32e30 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 le, if the inter
32e40 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 nal representati
32e50 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 on is FLOAT and
32e60 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a a text result.**
32e70 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b is requested, [
32e80 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
32e90 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 ()] is used inte
32ea0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 rnally to perfor
32eb0 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 m the.** convers
32ec0 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ion automaticall
32ed0 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 y. ^(The follow
32ee0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c ing table detail
32ef0 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e s the conversion
32f00 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 s.** that are ap
32f10 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c plied:.**.** <bl
32f20 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 ockquote>.** <ta
32f30 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a ble border="1">.
32f40 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 ** <tr><th> Inte
32f50 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 rnal<br>Type <th
32f60 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 > Requested<br>T
32f70 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 ype <th> Conver
32f80 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c sion.**.** <tr><
32f90 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
32fa0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e > INTEGER <td>
32fb0 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 Result is 0.**
32fc0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
32fd0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
32fe0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
32ff0 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 0.0.** <tr><td>
33000 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 NULL <td>
33010 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 TEXT <td> Res
33020 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ult is a NULL po
33030 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 inter.** <tr><td
33040 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
33050 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 BLOB <td> R
33060 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 esult is a NULL
33070 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c pointer.** <tr><
33080 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
33090 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
330a0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e Convert from in
330b0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a teger to float.*
330c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
330d0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 ER <td> TEXT
330e0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 <td> ASCII re
330f0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 ndering of the i
33100 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 nteger.** <tr><t
33110 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e d> INTEGER <td>
33120 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
33130 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d Same as INTEGER-
33140 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 >TEXT.** <tr><td
33150 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
33160 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b INTEGER <td> [
33170 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 CAST] to INTEGER
33180 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
33190 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OAT <td> TEX
331a0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 T <td> ASCII
331b0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
331c0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 float.** <tr><t
331d0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
331e0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
331f0 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a [CAST] to BLOB.*
33200 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
33210 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
33220 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 <td> [CAST] t
33230 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 o INTEGER.** <tr
33240 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
33250 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
33260 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 d> [CAST] to REA
33270 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 L.** <tr><td> T
33280 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c EXT <td> BL
33290 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 OB <td> No ch
332a0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ange.** <tr><td>
332b0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 BLOB <td> I
332c0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 NTEGER <td> [C
332d0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a AST] to INTEGER.
332e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f ** <tr><td> BLO
332f0 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 B <td> FLOAT
33300 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 <td> [CAST]
33310 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c to REAL.** <tr><
33320 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
33330 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
33340 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d Add a zero term
33350 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 inator if needed
33360 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 .** </table>.**
33370 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a </blockquote>)^.
33380 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
33390 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 when type conver
333a0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 sions occur, poi
333b0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 nters returned b
333c0 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 y prior.** calls
333d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
333e0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 mn_blob(), sqlit
333f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
33400 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 , and/or.** sqli
33410 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
33420 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 6() may be inval
33430 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 idated..** Type
33440 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 conversions and
33450 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 pointer invalida
33460 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 tions might occu
33470 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c r.** in the foll
33480 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a owing cases:.**.
33490 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
334a0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
334b0 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e ent is a BLOB an
334c0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
334d0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 _text() or.**
334e0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
334f0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 n_text16() is ca
33500 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 lled. A zero-te
33510 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a rminator might.*
33520 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 * need to b
33530 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 e added to the s
33540 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c tring.</li>.** <
33550 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 li> The initial
33560 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 content is UTF-8
33570 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 text and sqlite
33580 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
33590 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
335a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
335b0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e t16() is called.
335c0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 The content mu
335d0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a st be converted.
335e0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 ** to UTF-1
335f0 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 6.</li>.** <li>
33600 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
33610 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 ent is UTF-16 te
33620 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 xt and sqlite3_c
33630 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 olumn_bytes() or
33640 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
33650 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 _column_text() i
33660 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 s called. The c
33670 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 ontent must be c
33680 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 onverted.**
33690 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a to UTF-8.</li>.
336a0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e ** </ul>.**.** ^
336b0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 Conversions betw
336c0 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 een UTF-16be and
336d0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c UTF-16le are al
336e0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 ways done in pla
336f0 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 ce and do.** not
33700 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 invalidate a pr
33710 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f ior pointer, tho
33720 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 ugh of course th
33730 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
33740 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 buffer.** that
33750 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 the prior pointe
33760 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c r references wil
33770 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 l have been modi
33780 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e fied. Other kin
33790 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 ds.** of convers
337a0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 ion are done in
337b0 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 place when it is
337c0 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 possible, but s
337d0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a ometimes they.**
337e0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c are not possibl
337f0 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 e and in those c
33800 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 ases prior point
33810 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 ers are invalida
33820 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ted..**.** The s
33830 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 afest policy is
33840 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 to invoke these
33850 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f routines.** in o
33860 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
33870 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 ing ways:.**.**
33880 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c <ul>.** <li>sql
33890 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
338a0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 () followed by s
338b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
338c0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c tes()</li>.** <
338d0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d li>sqlite3_colum
338e0 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 n_blob() followe
338f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
33900 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e umn_bytes()</li>
33910 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
33920 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
33930 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
33940 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
33950 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f s16()</li>.** </
33960 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 ul>.**.** In oth
33970 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 er words, you sh
33980 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 ould call sqlite
33990 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 3_column_text(),
339a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
339b0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 mn_blob(), or sq
339c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
339d0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 t16() first to f
339e0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a orce the result.
339f0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 ** into the desi
33a00 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e red format, then
33a10 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
33a20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f column_bytes() o
33a30 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c r.** sqlite3_col
33a40 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f umn_bytes16() to
33a50 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f find the size o
33a60 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 f the result. D
33a70 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a o not mix calls.
33a80 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ** to sqlite3_co
33a90 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 lumn_text() or s
33aa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
33ab0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 ob() with calls
33ac0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f to.** sqlite3_co
33ad0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 lumn_bytes16(),
33ae0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 and do not mix c
33af0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
33b00 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a column_text16().
33b10 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f ** with calls to
33b20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
33b30 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e bytes()..**.** ^
33b40 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 The pointers ret
33b50 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 urned are valid
33b60 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e until a type con
33b70 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 version occurs a
33b80 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 s.** described a
33b90 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b bove, or until [
33ba0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
33bb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
33bc0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 t()] or.** [sqli
33bd0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
33be0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 is called. ^The
33bf0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 memory space us
33c00 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e ed to hold strin
33c10 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 gs.** and BLOBs
33c20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 is freed automat
33c30 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e ically. Do <em>
33c40 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 not</em> pass th
33c50 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 e pointers retur
33c60 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
33c70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
33c80 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f ()], [sqlite3_co
33c90 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 lumn_text()], et
33ca0 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 c. into.** [sqli
33cb0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a te3_free()]..**.
33cc0 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 ** ^(If a memory
33cd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
33ce0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 r occurs during
33cf0 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f the evaluation o
33d00 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 f any.** of thes
33d10 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 e routines, a de
33d20 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 fault value is r
33d30 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 eturned. The de
33d40 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 fault value.** i
33d50 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 s either the int
33d60 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 eger 0, the floa
33d70 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 ting point numbe
33d80 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c r 0.0, or a NULL
33d90 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 .** pointer. Su
33da0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
33db0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f o [sqlite3_errco
33dc0 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 de()] will retur
33dd0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d n.** [SQLITE_NOM
33de0 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 EM].)^.*/.SQLITE
33df0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
33e00 2a 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 *SQLITE_APICALL
33e10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
33e20 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
33e30 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
33e40 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
33e50 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 ITE_APICALL sqli
33e60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
33e70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
33e80 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
33e90 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
33ea0 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 _APICALL sqlite3
33eb0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
33ec0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
33ed0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
33ee0 5f 41 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 _API double SQLI
33ef0 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 TE_APICALL sqlit
33f00 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 e3_column_double
33f10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
33f20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
33f30 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
33f40 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 _APICALL sqlite3
33f50 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 _column_int(sqli
33f60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
33f70 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
33f80 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 sqlite3_int64 S
33f90 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 QLITE_APICALL sq
33fa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
33fb0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 64(sqlite3_stmt*
33fc0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
33fd0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e ITE_API const un
33fe0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c signed char *SQL
33ff0 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 ITE_APICALL sqli
34000 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
34010 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
34020 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
34030 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
34040 2a 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 *SQLITE_APICALL
34050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
34060 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ext16(sqlite3_st
34070 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
34080 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
34090 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 QLITE_APICALL sq
340a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
340b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
340c0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
340d0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 TE_API sqlite3_v
340e0 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 41 50 49 alue *SQLITE_API
340f0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
34100 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 umn_value(sqlite
34110 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
34120 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
34130 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 REF: Destroy A P
34140 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
34150 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 t Object.** DEST
34160 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f RUCTOR: sqlite3_
34170 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 stmt.**.** ^The
34180 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
34190 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 () function is c
341a0 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 alled to delete
341b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
341c0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 ement]..** ^If t
341d0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 he most recent e
341e0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 valuation of the
341f0 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 statement encou
34200 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 ntered no errors
34210 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 .** or if the st
34220 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 atement is never
34230 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c been evaluated,
34240 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 then sqlite3_fi
34250 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 nalize() returns
34260 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 .** SQLITE_OK.
34270 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
34280 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f ent evaluation o
34290 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 f statement S fa
342a0 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 iled, then.** sq
342b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 lite3_finalize(S
342c0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 ) returns the ap
342d0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 propriate [error
342e0 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 code] or.** [ex
342f0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
34300 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 e]..**.** ^The s
34310 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
34320 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 S) routine can b
34330 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 e called at any
34340 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 point during.**
34350 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f the life cycle o
34360 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 f [prepared stat
34370 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 ement] S:.** bef
34380 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 ore statement S
34390 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 is ever evaluate
343a0 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 d, after.** one
343b0 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f or more calls to
343c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
343d0 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 )], or after any
343e0 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c call.** to [sql
343f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 ite3_step()] reg
34400 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
34410 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 er or not the st
34420 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 atement has.** c
34430 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 ompleted executi
34440 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b on..**.** ^Invok
34450 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 ing sqlite3_fina
34460 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c lize() on a NULL
34470 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 pointer is a ha
34480 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a rmless no-op..**
34490 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
344a0 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a ion must finaliz
344b0 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 e every [prepare
344c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 d statement] in
344d0 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a order to avoid.*
344e0 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 * resource leaks
344f0 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 . It is a griev
34500 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 ous error for th
34510 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f e application to
34520 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 try to use.** a
34530 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
34540 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 ent after it has
34550 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e been finalized.
34560 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 Any use of a p
34570 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 repared.** state
34580 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 ment after it ha
34590 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 s been finalized
345a0 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 can result in u
345b0 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 ndefined and.**
345c0 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 undesirable beha
345d0 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 vior such as seg
345e0 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 faults and heap
345f0 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 corruption..*/.S
34600 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
34610 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c LITE_APICALL sql
34620 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 ite3_finalize(sq
34630 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
34640 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
34650 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 REF: Reset A Pre
34660 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 pared Statement
34670 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 Object.** METHOD
34680 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
34690 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
346a0 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f _reset() functio
346b0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 n is called to r
346c0 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 eset a [prepared
346d0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f statement].** o
346e0 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 bject back to it
346f0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c s initial state,
34700 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d ready to be re-
34710 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e executed..** ^An
34720 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 y SQL statement
34730 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 variables that h
34740 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 ad values bound
34750 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a to them using.**
34760 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 the [sqlite3_bi
34770 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 nd_blob | sqlite
34780 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 3_bind_*() API]
34790 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c retain their val
347a0 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c ues..** Use [sql
347b0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 ite3_clear_bindi
347c0 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 ngs()] to reset
347d0 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a the bindings..**
347e0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
347f0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 3_reset(S)] inte
34800 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 rface resets the
34810 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
34820 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 ment] S.** back
34830 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 to the beginning
34840 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e of its program.
34850 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d .**.** ^If the m
34860 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 ost recent call
34870 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
34880 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 (S)] for the.**
34890 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
348a0 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 ent] S returned
348b0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 [SQLITE_ROW] or
348c0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a [SQLITE_DONE],.*
348d0 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 * or if [sqlite3
348e0 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 _step(S)] has ne
348f0 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 ver before been
34900 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 called on S,.**
34910 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 then [sqlite3_re
34920 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 set(S)] returns
34930 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a [SQLITE_OK]..**.
34940 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
34950 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
34960 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
34970 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 for the.** [pre
34980 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
34990 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 S indicated an
349a0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b error, then.** [
349b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
349c0 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 ] returns an app
349d0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 ropriate [error
349e0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 code]..**.** ^Th
349f0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
34a00 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 (S)] interface d
34a10 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 oes not change t
34a20 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 he values.** of
34a30 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e any [sqlite3_bin
34a40 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d d_blob|bindings]
34a50 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 on the [prepare
34a60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a d statement] S..
34a70 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
34a80 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c t SQLITE_APICALL
34a90 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 sqlite3_reset(s
34aa0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
34ab0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
34ac0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 3REF: Create Or
34ad0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e Redefine SQL Fun
34ae0 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 ctions.** KEYWOR
34af0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 DS: {function cr
34b00 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d eation routines}
34b10 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 .** KEYWORDS: {a
34b20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
34b30 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d ed SQL function}
34b40 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 .** KEYWORDS: {a
34b50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
34b60 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
34b70 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c }.** METHOD: sql
34b80 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ite3.**.** ^Thes
34b90 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c e functions (col
34ba0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 lectively known
34bb0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 as "function cre
34bc0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 ation routines")
34bd0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 .** are used to
34be0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e add SQL function
34bf0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 s or aggregates
34c00 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 or to redefine t
34c10 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f he behavior.** o
34c20 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 f existing SQL f
34c30 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 unctions or aggr
34c40 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c egates. The onl
34c50 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 y differences be
34c60 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 tween.** these r
34c70 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 outines are the
34c80 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 text encoding ex
34c90 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 pected for.** th
34ca0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
34cb0 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 er (the name of
34cc0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 the function bei
34cd0 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 ng created).** a
34ce0 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 nd the presence
34cf0 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 or absence of a
34d00 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 destructor callb
34d10 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 ack for.** the a
34d20 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 pplication data
34d30 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
34d40 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
34d50 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 ter is the [data
34d60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
34d70 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 to which the SQ
34d80 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 L.** function is
34d90 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e to be added. ^
34da0 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f If an applicatio
34db0 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e n uses more than
34dc0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a one database.**
34dd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e connection then
34de0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
34df0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
34e00 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 ns must be added
34e10 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 .** to each data
34e20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
34e30 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a separately..**.*
34e40 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 * ^The second pa
34e50 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e rameter is the n
34e60 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 ame of the SQL f
34e70 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 unction to be cr
34e80 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 eated or.** rede
34e90 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e fined. ^The len
34ea0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 gth of the name
34eb0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 is limited to 25
34ec0 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 5 bytes in a UTF
34ed0 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 -8.** representa
34ee0 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 tion, exclusive
34ef0 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d of the zero-term
34f00 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 inator. ^Note t
34f10 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 hat the name.**
34f20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 length limit is
34f30 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 in UTF-8 bytes,
34f40 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e not characters n
34f50 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e or UTF-16 bytes.
34f60 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d .** ^Any attem
34f70 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 pt to create a f
34f80 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c unction with a l
34f90 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 onger name.** wi
34fa0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 ll result in [SQ
34fb0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 LITE_MISUSE] bei
34fc0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a ng returned..**.
34fd0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 ** ^The third pa
34fe0 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a rameter (nArg).*
34ff0 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 * is the number
35000 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 of arguments tha
35010 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
35020 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
35030 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 te takes. ^If th
35040 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 is parameter is
35050 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c -1, then the SQL
35060 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
35070 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 aggregate may ta
35080 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 ke any number of
35090 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 arguments betwe
350a0 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d en 0 and the lim
350b0 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 it.** set by [sq
350c0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 lite3_limit]([SQ
350d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
350e0 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 ION_ARG]). If t
350f0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 he third.** para
35100 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 meter is less th
35110 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 an -1 or greater
35120 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 than 127 then t
35130 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a he behavior is.*
35140 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a * undefined..**.
35150 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 ** ^The fourth p
35160 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 arameter, eTextR
35170 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 ep, specifies wh
35180 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 at.** [SQLITE_UT
35190 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 F8 | text encodi
351a0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e ng] this SQL fun
351b0 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f ction prefers fo
351c0 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 r.** its paramet
351d0 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 ers. The applic
351e0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 ation should set
351f0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 this parameter
35200 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 to.** [SQLITE_UT
35210 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 F16LE] if the fu
35220 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
35230 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a ation invokes .*
35240 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 * [sqlite3_value
35250 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 _text16le()] on
35260 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 an input, or [SQ
35270 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 LITE_UTF16BE] if
35280 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e the.** implemen
35290 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b tation invokes [
352a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
352b0 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 xt16be()] on an
352c0 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 input, or.** [SQ
352d0 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b LITE_UTF16] if [
352e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
352f0 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c xt16()] is used,
35300 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 or [SQLITE_UTF8
35310 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 ].** otherwise.
35320 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 ^The same SQL f
35330 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 unction may be r
35340 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 egistered multip
35350 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a le times using.*
35360 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 * different pref
35370 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 erred text encod
35380 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 ings, with diffe
35390 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 rent implementat
353a0 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 ions for.** each
353b0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 encoding..** ^W
353c0 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 hen multiple imp
353d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
353e0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
353f0 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c n are available,
35400 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 SQLite.** will
35410 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 pick the one tha
35420 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c t involves the l
35430 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 east amount of d
35440 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a ata conversion..
35450 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 **.** ^The fourt
35460 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 h parameter may
35470 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 optionally be OR
35480 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ed with [SQLITE_
35490 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a DETERMINISTIC].*
354a0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 * to signal that
354b0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 the function wi
354c0 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e ll always return
354d0 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 the same result
354e0 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 given.** the sa
354f0 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e me inputs within
35500 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 a single SQL st
35510 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 atement. Most S
35520 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 QL functions are
35530 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 .** deterministi
35540 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e c. The built-in
35550 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 [random()] SQL
35560 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 function is an e
35570 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 xample of a.** f
35580 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 unction that is
35590 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 not deterministi
355a0 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 c. The SQLite q
355b0 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 uery planner is
355c0 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f able to.** perfo
355d0 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 rm additional op
355e0 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 timizations on d
355f0 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e eterministic fun
35600 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a ctions, so use.*
35610 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 * of the [SQLITE
35620 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 _DETERMINISTIC]
35630 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e flag is recommen
35640 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 ded where possib
35650 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 le..**.** ^(The
35660 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 fifth parameter
35670 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 is an arbitrary
35680 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d pointer. The im
35690 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
356a0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 the.** function
356b0 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 can gain access
356c0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 to this pointer
356d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 using [sqlite3_u
356e0 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a ser_data()].)^.*
356f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c *.** ^The sixth,
35700 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 seventh and eig
35710 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 hth parameters,
35720 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 xFunc, xStep and
35730 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 xFinal, are.**
35740 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 pointers to C-la
35750 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 nguage functions
35760 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 that implement
35770 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
35780 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
35790 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 . ^A scalar SQL
357a0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
357b0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 s an implementat
357c0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 ion of the xFunc
357d0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c .** callback onl
357e0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 y; NULL pointers
357f0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 must be passed
35800 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 as the xStep and
35810 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d xFinal.** param
35820 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 eters. ^An aggre
35830 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
35840 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d n requires an im
35850 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
35860 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 xStep.** and xFi
35870 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 nal and NULL poi
35880 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 nter must be pas
35890 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e sed for xFunc. ^
358a0 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 To delete an exi
358b0 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e sting.** SQL fun
358c0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
358d0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f te, pass NULL po
358e0 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 inters for all t
358f0 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a hree function.**
35900 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a callbacks..**.*
35910 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 * ^(If the ninth
35920 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
35930 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
35940 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f ction_v2() is no
35950 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 t NULL,.** then
35960 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 it is destructor
35970 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 for the applica
35980 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 tion data pointe
35990 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 r. .** The destr
359a0 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 uctor is invoked
359b0 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 when the functi
359c0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 on is deleted, e
359d0 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a ither by being.*
359e0 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 * overloaded or
359f0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 when the databas
35a00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f e connection clo
35a10 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 ses.)^.** ^The d
35a20 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 estructor is als
35a30 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 o invoked if the
35a40 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 call 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 66 61 69 6c 73 2e 0a ion_v2() fails..
35a70 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 ** ^When the des
35a80 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b tructor callback
35a90 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 of the tenth pa
35aa0 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b rameter is invok
35ab0 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 ed, it.** is pas
35ac0 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 sed a single arg
35ad0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
35ae0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 copy of the app
35af0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a lication data .*
35b00 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 * pointer which
35b10 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 was the fifth pa
35b20 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
35b30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
35b40 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e on_v2()..**.** ^
35b50 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 It is permitted
35b60 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 to register mult
35b70 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 iple implementat
35b80 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
35b90 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 .** functions wi
35ba0 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 th the same name
35bb0 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 but with either
35bc0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 differing numbe
35bd0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e rs of.** argumen
35be0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 ts or differing
35bf0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 preferred text e
35c00 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 ncodings. ^SQLi
35c10 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 te will use.** t
35c20 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
35c30 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 n that most clos
35c40 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 ely matches the
35c50 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 way in which the
35c60 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e .** SQL function
35c70 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 is used. ^A fu
35c80 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
35c90 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e ation with a non
35ca0 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 -negative.** nAr
35cb0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 g parameter is a
35cc0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 better match th
35cd0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d an a function im
35ce0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 plementation wit
35cf0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 h.** a negative
35d00 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 nArg. ^A functi
35d10 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 on where the pre
35d20 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f ferred text enco
35d30 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 ding.** matches
35d40 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 the database enc
35d50 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 oding is a bette
35d60 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 r.** match than
35d70 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 a function where
35d80 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 the encoding is
35d90 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a different. .**
35da0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 ^A function whe
35db0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 re the encoding
35dc0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 difference is be
35dd0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e tween UTF16le an
35de0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 d UTF16be.** is
35df0 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 a closer match t
35e00 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 han a function w
35e10 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
35e20 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a g difference is.
35e30 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 ** between UTF8
35e40 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a and UTF16..**.**
35e50 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 ^Built-in funct
35e60 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 ions may be over
35e70 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 loaded by new ap
35e80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
35e90 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a d functions..**.
35ea0 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 ** ^An applicati
35eb0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
35ec0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 ion is permitted
35ed0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a to call other.*
35ee0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 * SQLite interfa
35ef0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 ces. However, s
35f00 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e uch calls must n
35f10 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 ot.** close the
35f20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
35f30 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 ion nor finalize
35f40 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 or reset the pr
35f50 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d epared.** statem
35f60 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 ent in which the
35f70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
35f80 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ning..*/.SQLITE_
35f90 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 API int SQLITE_A
35fa0 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 PICALL sqlite3_c
35fb0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a reate_function(.
35fc0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 sqlite3 *db,.
35fd0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 const char *zFu
35fe0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e nctionName,. in
35ff0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 t nArg,. int eT
36000 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a extRep,. void *
36010 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 53 51 pApp,. void (SQ
36020 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 LITE_CALLBACK *x
36030 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f Func)(sqlite3_co
36040 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
36050 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
36060 6f 69 64 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c oid (SQLITE_CALL
36070 42 41 43 4b 20 2a 78 53 74 65 70 29 28 73 71 6c BACK *xStep)(sql
36080 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
36090 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
360a0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 53 51 4c 49 *),. void (SQLI
360b0 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 46 69 TE_CALLBACK *xFi
360c0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e nal)(sqlite3_con
360d0 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 text*).);.SQLITE
360e0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
360f0 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f APICALL sqlite3_
36100 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
36110 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 6(. sqlite3 *db
36120 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a ,. const void *
36130 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 zFunctionName,.
36140 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 int nArg,. int
36150 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 eTextRep,. voi
36160 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 d *pApp,. void
36170 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b (SQLITE_CALLBACK
36180 20 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 *xFunc)(sqlite3
36190 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
361a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
361b0 20 20 76 6f 69 64 20 28 53 51 4c 49 54 45 5f 43 void (SQLITE_C
361c0 41 4c 4c 42 41 43 4b 20 2a 78 53 74 65 70 29 28 ALLBACK *xStep)(
361d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
361e0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
361f0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 53 ue**),. void (S
36200 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a QLITE_CALLBACK *
36210 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f xFinal)(sqlite3_
36220 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c context*).);.SQL
36230 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
36240 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 TE_APICALL sqlit
36250 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
36260 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 on_v2(. sqlite3
36270 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 *db,. const ch
36280 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d ar *zFunctionNam
36290 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 e,. int nArg,.
362a0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 int eTextRep,.
362b0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 void *pApp,. v
362c0 6f 69 64 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c oid (SQLITE_CALL
362d0 42 41 43 4b 20 2a 78 46 75 6e 63 29 28 73 71 6c BACK *xFunc)(sql
362e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
362f0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
36300 2a 29 2c 0a 20 20 76 6f 69 64 20 28 53 51 4c 49 *),. void (SQLI
36310 54 45 5f 43 41 4c 4c 42 41 43 4b 20 2a 78 53 74 TE_CALLBACK *xSt
36320 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
36330 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
36340 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
36350 64 20 28 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 d (SQLITE_CALLBA
36360 43 4b 20 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 CK *xFinal)(sqli
36370 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 te3_context*),.
36380 20 76 6f 69 64 28 53 51 4c 49 54 45 5f 43 41 4c void(SQLITE_CAL
36390 4c 42 41 43 4b 20 2a 78 44 65 73 74 72 6f 79 29 LBACK *xDestroy)
363a0 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a (void*).);../*.*
363b0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 * CAPI3REF: Text
363c0 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a Encodings.**.**
363d0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 These constant
363e0 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 define integer c
363f0 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 odes that repres
36400 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a ent the various.
36410 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ** text encoding
36420 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 s supported by S
36430 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e QLite..*/.#defin
36440 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 e SQLITE_UTF8
36450 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 1 /*
36460 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 IMP: R-37514-355
36470 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 66 */.#define SQ
36480 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 LITE_UTF16LE
36490 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 2 /* IMP:
364a0 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a R-03371-37637 *
364b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
364c0 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 _UTF16BE
364d0 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 3 /* IMP: R-5
364e0 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 1971-34154 */.#d
364f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
36500 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 16 4
36510 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 /* Use native b
36520 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 yte order */.#de
36530 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 fine SQLITE_ANY
36540 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 5
36550 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f /* Deprecated */
36560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
36570 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 UTF16_ALIGNED 8
36580 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 /* sqlite3_c
36590 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 reate_collation
365a0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 only */../*.** C
365b0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f API3REF: Functio
365c0 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 n Flags.**.** Th
365d0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 ese constants ma
365e0 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 y be ORed togeth
365f0 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 er with the .**
36600 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 [SQLITE_UTF8 | p
36610 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
36620 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 coding] as the f
36630 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a ourth argument.*
36640 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 * to [sqlite3_cr
36650 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
36660 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 , [sqlite3_creat
36670 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c e_function16()],
36680 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
36690 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
366a0 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e v2()]..*/.#defin
366b0 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 e SQLITE_DETERMI
366c0 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a NISTIC 0x800.
366d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
366e0 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 Deprecated Func
366f0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 tions.** DEPRECA
36700 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TED.**.** These
36710 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 functions are [d
36720 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 eprecated]. In
36730 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 order to maintai
36740 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 n.** backwards c
36750 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 ompatibility wit
36760 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 h older code, th
36770 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f ese functions co
36780 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 ntinue .** to be
36790 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 supported. How
367a0 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 ever, new applic
367b0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 ations should av
367c0 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f oid.** the use o
367d0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e f these function
367e0 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 s. To encourage
367f0 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 programmers to
36800 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 avoid.** these f
36810 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c unctions, we wil
36820 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 l not explain wh
36830 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 at they do..*/.#
36840 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d ifndef SQLITE_OM
36850 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 IT_DEPRECATED.SQ
36860 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
36870 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 DEPRECATED int S
36880 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 QLITE_APICALL sq
36890 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
368a0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f count(sqlite3_co
368b0 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f ntext*);.SQLITE_
368c0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
368d0 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 CATED int SQLITE
368e0 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 _APICALL sqlite3
368f0 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 _expired(sqlite3
36900 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f _stmt*);.SQLITE_
36910 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
36920 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 CATED int SQLITE
36930 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 _APICALL sqlite3
36940 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e _transfer_bindin
36950 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a gs(sqlite3_stmt*
36960 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 , sqlite3_stmt*)
36970 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c ;.SQLITE_API SQL
36980 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
36990 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c nt SQLITE_APICAL
369a0 4c 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c L sqlite3_global
369b0 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a _recover(void);.
369c0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
369d0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 E_DEPRECATED voi
369e0 64 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c d SQLITE_APICALL
369f0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f sqlite3_thread_
36a00 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 cleanup(void);.S
36a10 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
36a20 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
36a30 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 SQLITE_APICALL s
36a40 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c qlite3_memory_al
36a50 61 72 6d 28 76 6f 69 64 28 53 51 4c 49 54 45 5f arm(void(SQLITE_
36a60 43 41 4c 4c 42 41 43 4b 20 2a 29 28 76 6f 69 64 CALLBACK *)(void
36a70 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c *,sqlite3_int64,
36a80 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 int),.
36a90 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
36aa0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 *,sqlite3_int64)
36ab0 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 ;.#endif../*.**
36ac0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e CAPI3REF: Obtain
36ad0 69 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a ing SQL Values.*
36ae0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
36af0 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 3_value.**.** Th
36b00 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 e C-language imp
36b10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 lementation of S
36b20 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 QL functions and
36b30 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 aggregates uses
36b40 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 .** this set of
36b50 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e interface routin
36b60 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 es to access the
36b70 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 parameter value
36b80 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 s on.** the func
36b90 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 tion or aggregat
36ba0 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 e. .**.** The x
36bb0 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 Func (for scalar
36bc0 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 functions) or x
36bd0 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 Step (for aggreg
36be0 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 ates) parameters
36bf0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f .** to [sqlite3_
36c00 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
36c10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
36c20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
36c30 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 6()].** define c
36c40 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d allbacks that im
36c50 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 plement the SQL
36c60 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
36c70 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 gregates..** The
36c80 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
36c90 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b o these callback
36ca0 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 s is an array of
36cb0 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 pointers to.**
36cc0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
36cd0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
36ce0 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 s. There is one
36cf0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
36d00 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 object for.** e
36d10 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f ach parameter to
36d20 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
36d30 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e n. These routin
36d40 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a es are used to.*
36d50 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 * extract values
36d60 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 from the [sqlit
36d70 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
36d80 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s..**.** These r
36d90 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c outines work onl
36da0 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 y with [protecte
36db0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
36dc0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 objects..** Any
36dd0 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 attempt to use
36de0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f these routines o
36df0 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 n an [unprotecte
36e00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
36e10 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c .** object resul
36e20 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 ts in undefined
36e30 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 behavior..**.**
36e40 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
36e50 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 work just like t
36e60 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
36e70 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 [column access
36e80 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 functions].** ex
36e90 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20 cept that these
36ea0 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 routines take a
36eb0 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 single [protecte
36ec0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
36ed0 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 object.** point
36ee0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 er instead of a
36ef0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 [sqlite3_stmt*]
36f00 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 pointer and an i
36f10 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 nteger column nu
36f20 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 mber..**.** ^The
36f30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
36f40 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 ext16() interfac
36f50 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 e extracts a UTF
36f60 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e -16 string.** in
36f70 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
36f80 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f -order of the ho
36f90 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 st machine. ^Th
36fa0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c e.** sqlite3_val
36fb0 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e ue_text16be() an
36fc0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f d sqlite3_value_
36fd0 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 text16le() inter
36fe0 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 faces.** extract
36ff0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 UTF-16 strings
37000 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e as big-endian an
37010 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 d little-endian
37020 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a respectively..**
37030 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 .** ^(The sqlite
37040 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 3_value_numeric_
37050 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 type() interface
37060 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 attempts to app
37070 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 ly.** numeric af
37080 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 finity to the va
37090 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 lue. This means
370a0 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 that an attempt
370b0 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 is.** made to c
370c0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 onvert the value
370d0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f to an integer o
370e0 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 r floating point
370f0 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 . If.** such a
37100 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f conversion is po
37110 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c ssible without l
37120 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 oss of informati
37130 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 on (in other.**
37140 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 words, if the va
37150 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 lue is a string
37160 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 that looks like
37170 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 a number).** the
37180 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e n the conversion
37190 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 is performed.
371a0 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e Otherwise no con
371b0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a version occurs..
371c0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 ** The [SQLITE_I
371d0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 NTEGER | datatyp
371e0 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 e] after convers
371f0 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e ion is returned.
37200 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 )^.**.** Please
37210 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 pay particular a
37220 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 ttention to the
37230 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f fact that the po
37240 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a inter returned.*
37250 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
37260 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b value_blob()], [
37270 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
37280 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 xt()], or.** [sq
37290 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
372a0 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 16()] can be inv
372b0 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 alidated by a su
372c0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f bsequent call to
372d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
372e0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 ue_bytes()], [sq
372f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
37300 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 s16()], [sqlite3
37310 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a _value_text()],.
37320 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 ** or [sqlite3_v
37330 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a alue_text16()]..
37340 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
37350 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c ines must be cal
37360 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
37370 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 e thread as.** t
37380 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
37390 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 that supplied th
373a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
373b0 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a *] parameters..*
373c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
373d0 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f st void *SQLITE_
373e0 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f APICALL sqlite3_
373f0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 value_blob(sqlit
37400 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
37410 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
37420 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 E_APICALL sqlite
37430 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 3_value_bytes(sq
37440 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
37450 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
37460 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c LITE_APICALL sql
37470 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
37480 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 16(sqlite3_value
37490 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 *);.SQLITE_API d
374a0 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 41 50 49 ouble SQLITE_API
374b0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c CALL sqlite3_val
374c0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 ue_double(sqlite
374d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
374e0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
374f0 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 _APICALL sqlite3
37500 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 _value_int(sqlit
37510 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
37520 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 TE_API sqlite3_i
37530 6e 74 36 34 20 53 51 4c 49 54 45 5f 41 50 49 43 nt64 SQLITE_APIC
37540 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ALL sqlite3_valu
37550 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f e_int64(sqlite3_
37560 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
37570 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e API const unsign
37580 65 64 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f ed char *SQLITE_
37590 41 50 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f APICALL sqlite3_
375a0 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 value_text(sqlit
375b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
375c0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
375d0 64 20 2a 53 51 4c 49 54 45 5f 41 50 49 43 41 4c d *SQLITE_APICAL
375e0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f L sqlite3_value_
375f0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 text16(sqlite3_v
37600 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
37610 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 PI const void *S
37620 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 QLITE_APICALL sq
37630 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
37640 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 16le(sqlite3_val
37650 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
37660 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c const void *SQL
37670 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 6c 69 ITE_APICALL sqli
37680 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
37690 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 be(sqlite3_value
376a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
376b0 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c nt SQLITE_APICAL
376c0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f L sqlite3_value_
376d0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c type(sqlite3_val
376e0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
376f0 20 69 6e 74 20 53 51 4c 49 54 45 5f 41 50 49 43 int SQLITE_APIC
37700 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ALL sqlite3_valu
37710 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 e_numeric_type(s
37720 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
37730 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
37740 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 Finding The Sub
37750 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 type Of SQL Valu
37760 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 es.** METHOD: sq
37770 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a lite3_value.**.*
37780 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 * The sqlite3_va
37790 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 lue_subtype(V) f
377a0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
377b0 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a the subtype for.
377c0 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 ** an [applicati
377d0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
377e0 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e unction] argumen
377f0 74 20 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 t V. The subtyp
37800 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e e.** information
37810 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
37820 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 pass a limited a
37830 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 mount of context
37840 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c from.** one SQL
37850 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f function to ano
37860 74 68 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b ther. Use the [
37870 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 sqlite3_result_s
37880 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 ubtype()].** rou
37890 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 tine to set the
378a0 73 75 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 subtype for the
378b0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
378c0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e an SQL function.
378d0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 .**.** SQLite ma
378e0 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 kes no use of su
378f0 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49 btype itself. I
37900 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20 t merely passes
37910 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 the subtype.** f
37920 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f rom the result o
37930 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 f one [applicati
37940 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
37950 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 unction] into th
37960 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e e.** input of an
37970 6f 74 68 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 other..*/.SQLITE
37980 5f 41 50 49 20 75 6e 73 69 67 6e 65 64 20 69 6e _API unsigned in
37990 74 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c t SQLITE_APICALL
379a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 sqlite3_value_s
379b0 75 62 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 ubtype(sqlite3_v
379c0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 alue*);../*.** C
379d0 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e API3REF: Copy An
379e0 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 d Free SQL Value
379f0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
37a00 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a ite3_value.**.**
37a10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^The sqlite3_va
37a20 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 lue_dup(V) inter
37a30 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 face makes a cop
37a40 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 y of the [sqlite
37a50 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 3_value].** obje
37a60 63 74 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 ct D and returns
37a70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
37a80 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b at copy. ^The [
37a90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 sqlite3_value] r
37aa0 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 eturned.** is a
37ab0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
37ac0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
37ad0 20 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 even if the inp
37ae0 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 ut is not..** ^T
37af0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
37b00 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 _dup(V) interfac
37b10 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 e returns NULL i
37b20 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 f V is NULL or i
37b30 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c f a.** memory al
37b40 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a location fails..
37b50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
37b60 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 e3_value_free(V)
37b70 20 69 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 interface frees
37b80 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c an [sqlite3_val
37b90 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 ue] object.** pr
37ba0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 eviously obtaine
37bb0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
37bc0 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e value_dup()]. ^
37bd0 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 If V is a NULL p
37be0 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 ointer.** then s
37bf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 qlite3_value_fre
37c00 65 28 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 e(V) is a harmle
37c10 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c ss no-op..*/.SQL
37c20 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
37c30 76 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 41 50 value *SQLITE_AP
37c40 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 ICALL sqlite3_va
37c50 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 lue_dup(const sq
37c60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
37c70 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 QLITE_API void S
37c80 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 20 73 71 QLITE_APICALL sq
37c90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 lite3_value_free
37ca0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
37cb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
37cc0 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 F: Obtain Aggreg
37cd0 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e ate Function Con
37ce0 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 text.** METHOD:
37cf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a sqlite3_context.
37d00 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 **.** Implementa
37d10 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 tions of aggrega
37d20 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 te SQL functions
37d30 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 use this.** rou
37d40 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 tine to allocate
37d50 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 memory for stor
37d60 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e ing their state.
37d70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
37d80 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 t time the sqlit
37d90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
37da0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e text(C,N) routin
37db0 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 e is called .**
37dc0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
37dd0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
37de0 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 ion, SQLite.** a
37df0 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 llocates N of me
37e00 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 mory, zeroes out
37e10 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e that memory, an
37e20 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e d returns a poin
37e30 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 ter.** to the ne
37e40 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 w memory. ^On se
37e50 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 cond and subsequ
37e60 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 ent calls to.**
37e70 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
37e80 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 e_context() for
37e90 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 the same aggrega
37ea0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 te function inst
37eb0 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d ance,.** the sam
37ec0 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 e buffer is retu
37ed0 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 rned. Sqlite3_a
37ee0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
37ef0 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a () is normally.*
37f00 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f * called once fo
37f10 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f r each invocatio
37f20 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 n of the xStep c
37f30 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e allback and then
37f40 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d one.** last tim
37f50 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 e when the xFina
37f60 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e l callback is in
37f70 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e voked. ^(When n
37f80 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 o rows match.**
37f90 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 an aggregate que
37fa0 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 ry, the xStep()
37fb0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 callback of the
37fc0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
37fd0 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 on.** implementa
37fe0 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 tion is never ca
37ff0 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 lled and xFinal(
38000 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 ) is called exac
38010 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 tly once..** In
38020 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c those cases, sql
38030 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
38040 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 ontext() might b
38050 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 e called for the
38060 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 .** first time f
38070 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 rom within xFina
38080 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 l().)^.**.** ^Th
38090 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 e sqlite3_aggreg
380a0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
380b0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
380c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
380d0 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 .** when first c
380e0 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 alled if N is le
380f0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c ss than or equal
38100 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 to zero or if a
38110 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
38120 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ate error occurs
38130 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d ..**.** ^(The am
38140 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c ount of space al
38150 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 located by sqlit
38160 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
38170 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 text(C,N) is.**
38180 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 determined by th
38190 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e e N parameter on
381a0 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 first successfu
381b0 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e l call. Changin
381c0 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f g the.** value o
381d0 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e f N in subsequen
381e0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 t call to sqlite
381f0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
38200 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 ext() within.**
38210 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 the same aggrega
38220 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 te function inst
38230 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 ance will not re
38240 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a size the memory.
38250 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e ** allocation.)^
38260 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 Within the xFi
38270 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 nal callback, it
38280 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f is customary to
38290 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 set.** N=0 in c
382a0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
382b0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
382c0 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e t(C,N) so that n
382d0 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 o .** pointless
382e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
382f0 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 ns occur..**.**
38300 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 ^SQLite automati
38310 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 cally frees the
38320 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 memory allocated
38330 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f by .** sqlite3_
38340 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
38350 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 t() when the agg
38360 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e regate query con
38370 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 cludes..**.** Th
38380 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
38390 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 r must be a copy
383a0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
383b0 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 te3_context | SQ
383c0 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 L function conte
383d0 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 xt] that is the
383e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a first parameter.
383f0 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 ** to the xStep
38400 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 or xFinal callba
38410 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 ck routine that
38420 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 implements the a
38430 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 ggregate.** func
38440 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 tion..**.** This
38450 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 routine must be
38460 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
38470 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
38480 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 which.** the agg
38490 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
384a0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
384b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
384c0 69 64 20 2a 53 51 4c 49 54 45 5f 41 50 49 43 41 id *SQLITE_APICA
384d0 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 LL sqlite3_aggre
384e0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c gate_context(sql
384f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
38500 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a nt nBytes);../*.
38510 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 ** CAPI3REF: Use
38520 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 r Data For Funct
38530 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ions.** METHOD:
38540 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a sqlite3_context.
38550 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
38560 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 e3_user_data() i
38570 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
38580 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 a copy of.** th
38590 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 e pointer that w
385a0 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 as the pUserData
385b0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 parameter (the
385c0 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 5th parameter).*
385d0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
385e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
385f0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c n()].** and [sql
38600 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
38610 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e tion16()] routin
38620 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c es that original
38630 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 ly.** registered
38640 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
38650 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f defined functio
38660 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f n..**.** This ro
38670 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 utine must be ca
38680 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 lled from the sa
38690 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 me thread in whi
386a0 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 ch.** the applic
386b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
386c0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
386d0 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 g..*/.SQLITE_API
386e0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 41 50 void *SQLITE_AP
386f0 49 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 73 ICALL sqlite3_us
38700 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f er_data(sqlite3_
38710 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a context*);../*.*
38720 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
38730 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
38740 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a For Functions.**
38750 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
38760 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e _context.**.** ^
38770 54 68