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 5f 53 51 4c .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 ITE3_H_.#define
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 lude <stdarg.h>
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 /*.** Make sure
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61 ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69 bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75 de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 TE_API.# define
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20 _CDECL.# define
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66 TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20 ros are used in
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 e.** interfaces
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63 as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65 ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 ntal. New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63 d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20 ated interfaces
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 ity only. Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 ese macros used
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 sages when they
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 were used. But
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 magic ended up
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 generating such
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 a flurry of bug
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 reports.** that
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 e back to using
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 not defined by
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 n Numbers.**.**
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20 Lite3) and Y is
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72 _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 0 + Y*1000 + Z)
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 where X, Y, and
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69 * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 te will also.**
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 he release from
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69 which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77 ved. Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 system</a>. ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f m. ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31 UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20 .** hash of the
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72 entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 QLITE_VERSION
10a0: 20 20 20 20 20 22 33 2e 38 2e 31 31 22 0a 23 64 "3.8.11".#d
10b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 efine SQLITE_VER
10c0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 38 SION_NUMBER 3008
10d0: 30 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 011.#define SQLI
10e0: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20 TE_SOURCE_ID
10f0: 20 20 22 32 30 31 35 2d 30 37 2d 31 34 20 32 31 "2015-07-14 21
1100: 3a 35 36 3a 35 33 20 62 35 33 61 39 35 30 36 33 :56:53 b53a95063
1110: 63 66 36 62 38 65 65 38 63 61 64 37 37 65 39 66 cf6b8ee8cad77e9f
1120: 66 66 34 63 35 30 61 33 35 36 63 34 33 62 62 22 ff4c50a356c43bb"
1130: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1140: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 : Run-Time Libra
1150: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 ry Version Numbe
1160: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 rs.** KEYWORDS:
1170: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c sqlite3_version,
1180: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 sqlite3_sourcei
1190: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e d.**.** These in
11a0: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 terfaces provide
11b0: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d the same inform
11c0: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 ation as the [SQ
11d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a LITE_VERSION],.*
11e0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f * [SQLITE_VERSIO
11f0: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b N_NUMBER], and [
1200: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
1210: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
1220: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 macros.** but a
1230: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 re associated wi
1240: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 th the library i
1250: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 nstead of the he
1260: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 ader file. ^(Ca
1270: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 utious.** progra
1280: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c mmers might incl
1290: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 ude assert() sta
12a0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 tements in their
12b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a application to.
12c0: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76 ** verify that v
12d0: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
12e0: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 y these interfac
12f0: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 es match the mac
1300: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 ros in.** the he
1310: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 69 ader, and thus i
1320: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61 nsure that the a
1330: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a pplication is.**
1340: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d compiled with m
1350: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 atching library
1360: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 and header files
1370: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 ..**.** <blockqu
1380: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 ote><pre>.** ass
1390: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 ert( sqlite3_lib
13a0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 version_number()
13b0: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e ==SQLITE_VERSION
13c0: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 _NUMBER );.** as
13d0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c sert( strcmp(sql
13e0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c ite3_sourceid(),
13f0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
1400: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 )==0 );.** asser
1410: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 t( strcmp(sqlite
1420: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 3_libversion(),S
1430: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d QLITE_VERSION)==
1440: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 0 );.** </pre></
1450: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
1460: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1470: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e _version[] strin
1480: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 g constant conta
1490: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 ins the text of
14a0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d [SQLITE_VERSION]
14b0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 .** macro. ^The
14c0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
14d0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ion() function r
14e0: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
14f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 to the.** to th
1500: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f e sqlite3_versio
1510: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 n[] string const
1520: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ant. The sqlite
1530: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 3_libversion().*
1540: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 * function is pr
1550: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 ovided for use i
1560: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c n DLLs since DLL
1570: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 users usually d
1580: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 o not have.** di
1590: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 rect access to s
15a0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 tring constants
15b0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 within the DLL.
15c0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
15d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
15e0: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 er() function re
15f0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 turns an integer
1600: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 equal to.** [SQ
1610: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
1620: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 BER]. ^The sqli
1630: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 te3_sourceid() f
1640: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1650: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
1660: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 a string consta
1670: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 nt whose value i
1680: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 s the same as th
1690: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f e .** [SQLITE_SO
16a0: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 URCE_ID] C prepr
16b0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a ocessor macro..*
16c0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
16d0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 sqlite_version()
16e0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f ] and [sqlite_so
16f0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 urce_id()]..*/.S
1700: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
1710: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 _EXTERN const ch
1720: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 ar sqlite3_versi
1730: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49 on[];.SQLITE_API
1740: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
1750: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
1760: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 te3_libversion(v
1770: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
1780: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
1790: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
17a0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 te3_sourceid(voi
17b0: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 d);.SQLITE_API i
17c0: 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
17d0: 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 L sqlite3_libver
17e0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 sion_number(void
17f0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1800: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 EF: Run-Time Lib
1810: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e rary Compilation
1820: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 Options Diagnos
1830: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 tics.**.** ^The
1840: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f sqlite3_compileo
1850: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e ption_used() fun
1860: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 ction returns 0
1870: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 or 1 .** indicat
1880: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20 ing whether the
1890: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e specified option
18a0: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 was defined at
18b0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 .** compile time
18c0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 . ^The SQLITE_
18d0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d prefix may be om
18e0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a itted from the .
18f0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 ** option name p
1900: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 assed to sqlite3
1910: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 _compileoption_u
1920: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e sed(). .**.** ^
1930: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 The sqlite3_comp
1940: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 ileoption_get()
1950: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 function allows
1960: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 iterating.** ove
1970: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 r the list of op
1980: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 tions that were
1990: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 defined at compi
19a0: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 le time by.** re
19b0: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 turning the N-th
19c0: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 compile time op
19d0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 tion string. ^I
19e0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 f N is out of ra
19f0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f nge,.** sqlite3_
1a00: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 compileoption_ge
1a10: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 t() returns a NU
1a20: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 LL pointer. ^Th
1a30: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 e SQLITE_ .** pr
1a40: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 efix is omitted
1a50: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 from any strings
1a60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a returned by .**
1a70: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1a80: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a option_get()..**
1a90: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 .** ^Support for
1aa0: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 the diagnostic
1ab0: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 functions sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 3_compileoption_
1ad0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 used().** and sq
1ae0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
1af0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 ion_get() may be
1b00: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 omitted by spec
1b10: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b ifying the .** [
1b20: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 SQLITE_OMIT_COMP
1b30: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d ILEOPTION_DIAGS]
1b40: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 option at compi
1b50: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 le time..**.** S
1b60: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e ee also: SQL fun
1b70: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 ctions [sqlite_c
1b80: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1b90: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c d()] and.** [sql
1ba0: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f ite_compileoptio
1bb0: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 n_get()] and the
1bc0: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e [compile_option
1bd0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 s pragma]..*/.#i
1be0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 fndef SQLITE_OMI
1bf0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f T_COMPILEOPTION_
1c00: 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 DIAGS.SQLITE_API
1c10: 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
1c20: 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 ALL sqlite3_comp
1c30: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 ileoption_used(c
1c40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e onst char *zOptN
1c50: 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ame);.SQLITE_API
1c60: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
1c70: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
1c80: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
1c90: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 n_get(int N);.#e
1ca0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
1cb0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 3REF: Test To Se
1cc0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 e If The Library
1cd0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a Is Threadsafe.*
1ce0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1cf0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 3_threadsafe() f
1d00: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1d10: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 zero if and only
1d20: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 if.** SQLite wa
1d30: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
1d40: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d mutexing code om
1d50: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 itted due to the
1d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 .** [SQLITE_THRE
1d70: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d ADSAFE] compile-
1d80: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e time option bein
1d90: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a g set to 0..**.*
1da0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 * SQLite can be
1db0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 compiled with or
1dc0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 without mutexes
1dd0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b . When.** the [
1de0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
1df0: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f E] C preprocesso
1e00: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 r macro is 1 or
1e10: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 2, mutexes.** ar
1e20: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 e enabled and SQ
1e30: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61 Lite is threadsa
1e40: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a fe. When the.**
1e50: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
1e60: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c AFE] macro is 0,
1e70: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 .** the mutexes
1e80: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 are omitted. W
1e90: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 ithout the mutex
1ea0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 es, it is not sa
1eb0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c fe.** to use SQL
1ec0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 ite concurrently
1ed0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 from more than
1ee0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a one thread..**.*
1ef0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 * Enabling mutex
1f00: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 es incurs a meas
1f10: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e urable performan
1f20: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 ce penalty..** S
1f30: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 o if speed is of
1f40: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e utmost importan
1f50: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e ce, it makes sen
1f60: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a se to disable.**
1f70: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 the mutexes. B
1f80: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 ut for maximum s
1f90: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 afety, mutexes s
1fa0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 hould be enabled
1fb0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c ..** ^The defaul
1fc0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f t behavior is fo
1fd0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 r mutexes to be
1fe0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 enabled..**.** T
1ff0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 his interface ca
2000: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 n be used by an
2010: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d application to m
2020: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68 ake sure that th
2030: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 e.** version of
2040: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 SQLite that it i
2050: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 s linking agains
2060: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 t was compiled w
2070: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 ith.** the desir
2080: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 ed setting of th
2090: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
20a0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a SAFE] macro..**.
20b0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
20c0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f e only reports o
20d0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 n the compile-ti
20e0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 me mutex setting
20f0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 .** of the [SQLI
2100: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 TE_THREADSAFE] f
2110: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 lag. If SQLite
2120: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
2130: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 .** SQLITE_THREA
2140: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 DSAFE=1 or =2 th
2150: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 en mutexes are e
2160: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c nabled by defaul
2170: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 t but.** can be
2180: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c fully or partial
2190: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e ly disabled usin
21a0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c g a call to [sql
21b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a ite3_config()].*
21c0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 * with the verbs
21d0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
21e0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b SINGLETHREAD], [
21f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
2200: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f LTITHREAD],.** o
2210: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 r [SQLITE_CONFIG
2220: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e _SERIALIZED]. ^
2230: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 (The return valu
2240: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 e of the.** sqli
2250: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 te3_threadsafe()
2260: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 function shows
2270: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 only the compile
2280: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 -time setting of
2290: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 .** thread safet
22a0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 y, not any run-t
22b0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 ime changes to t
22c0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 hat setting made
22d0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 by.** sqlite3_c
22e0: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 onfig(). In othe
22f0: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 r words, the ret
2300: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 urn value from s
2310: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
2320: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e e().** is unchan
2330: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 ged by calls to
2340: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
2350: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 .)^.**.** See th
2360: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
2370: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e e] documentation
2380: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
2390: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a information..*/.
23a0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
23b0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
23c0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
23d0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 (void);../*.** C
23e0: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
23f0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e e Connection Han
2400: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a dle.** KEYWORDS:
2410: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 {database conne
2420: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 ction} {database
2430: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a connections}.**
2440: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 .** Each open SQ
2450: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 Lite database is
2460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
2470: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
2480: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 instance of.** t
2490: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 he opaque struct
24a0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 ure named "sqlit
24b0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 e3". It is usef
24c0: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 ul to think of a
24d0: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 n sqlite3.** poi
24e0: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 nter as an objec
24f0: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 t. The [sqlite3
2500: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
2510: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e e3_open16()], an
2520: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 d.** [sqlite3_op
2530: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
2540: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 ces are its cons
2550: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 tructors, and [s
2560: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a qlite3_close()].
2570: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
2580: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 close_v2()] are
2590: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e its destructors.
25a0: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 There are many
25b0: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 other.** interf
25c0: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a aces (such as.**
25d0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
25e0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 e_v2()], [sqlite
25f0: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2600: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 n()], and.** [sq
2610: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
2620: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 ut()] to name bu
2630: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 t three) that ar
2640: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a e methods on an.
2650: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 ** sqlite3 objec
2660: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 t..*/.typedef st
2670: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c ruct sqlite3 sql
2680: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ite3;../*.** CAP
2690: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e I3REF: 64-Bit In
26a0: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b teger Types.** K
26b0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f EYWORDS: sqlite_
26c0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e int64 sqlite_uin
26d0: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 t64.**.** Becaus
26e0: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 e there is no cr
26f0: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 oss-platform way
2700: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 to specify 64-b
2710: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 it integer types
2720: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 .** SQLite inclu
2730: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 des typedefs for
2740: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 64-bit signed a
2750: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 nd unsigned inte
2760: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 gers..**.** The
2770: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e sqlite3_int64 an
2780: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 d sqlite3_uint64
2790: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 are the preferr
27a0: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 ed type definiti
27b0: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ons..** The sqli
27c0: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c te_int64 and sql
27d0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 ite_uint64 types
27e0: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 are supported f
27f0: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 or backwards.**
2800: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e compatibility on
2810: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ly..**.** ^The s
2820: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 qlite3_int64 and
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 sqlite_int64 ty
2840: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e pes can store in
2850: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 teger values.**
2860: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 between -9223372
2870: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 036854775808 and
2880: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 +92233720368547
2890: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 75807 inclusive.
28a0: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 ^The.** sqlite
28b0: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 3_uint64 and sql
28c0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 ite_uint64 types
28d0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 can store integ
28e0: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 er values .** be
28f0: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 tween 0 and +184
2900: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 4674407370955161
2910: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 5 inclusive..*/.
2920: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e #ifdef SQLITE_IN
2930: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 T64_TYPE. typed
2940: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f ef SQLITE_INT64_
2950: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 TYPE sqlite_int6
2960: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 4;. typedef uns
2970: 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 igned SQLITE_INT
2980: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 64_TYPE sqlite_u
2990: 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 int64;.#elif def
29a0: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c ined(_MSC_VER) |
29b0: 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c | defined(__BORL
29c0: 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 ANDC__). typede
29d0: 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 f __int64 sqlite
29e0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 _int64;. typede
29f0: 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 f unsigned __int
2a00: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 64 sqlite_uint64
2a10: 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 ;.#else. typede
2a20: 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 f long long int
2a30: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 sqlite_int64;.
2a40: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 typedef unsigned
2a50: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 long long int s
2a60: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 qlite_uint64;.#e
2a70: 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c ndif.typedef sql
2a80: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 ite_int64 sqlite
2a90: 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 3_int64;.typedef
2aa0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 sqlite_uint64 s
2ab0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a qlite3_uint64;..
2ac0: 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 /*.** If compili
2ad0: 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 ng for a process
2ae0: 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c or that lacks fl
2af0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 oating point sup
2b00: 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 port,.** substit
2b10: 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 ute integer for
2b20: 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a floating-point..
2b30: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 */.#ifdef SQLITE
2b40: 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 _OMIT_FLOATING_P
2b50: 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f OINT.# define do
2b60: 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 uble sqlite3_int
2b70: 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 64.#endif../*.**
2b80: 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 CAPI3REF: Closi
2b90: 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f ng A Database Co
2ba0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 nnection.** DEST
2bb0: 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a RUCTOR: sqlite3.
2bc0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2bd0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 e3_close() and s
2be0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
2bf0: 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 ) routines are d
2c00: 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f estructors.** fo
2c10: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 r the [sqlite3]
2c20: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c object..** ^Call
2c30: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f s to sqlite3_clo
2c40: 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 se() and sqlite3
2c50: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75 _close_v2() retu
2c60: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 rn [SQLITE_OK] i
2c70: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 f.** the [sqlite
2c80: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63 3] object is suc
2c90: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f cessfully destro
2ca0: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f yed and all asso
2cb0: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 ciated.** resour
2cc0: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 ces are dealloca
2cd0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ted..**.** ^If t
2ce0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
2cf0: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 ection is associ
2d00: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 ated with unfina
2d10: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a lized prepared.*
2d20: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 * statements or
2d30: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 unfinished sqlit
2d40: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 e3_backup object
2d50: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 s then sqlite3_c
2d60: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c lose().** will l
2d70: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73 eave the databas
2d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 e connection ope
2d90: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 n and return [SQ
2da0: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e LITE_BUSY]..** ^
2db0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 If sqlite3_close
2dc0: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 _v2() is called
2dd0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 with unfinalized
2de0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2df0: 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 ents.** and/or u
2e00: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 nfinished sqlite
2e10: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 3_backups, then
2e20: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2e30: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a nection becomes.
2e40: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 ** an unusable "
2e50: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 zombie" which wi
2e60: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
2e70: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
2e80: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 when the.** last
2e90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2ea0: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 ent is finalized
2eb0: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c or the last sql
2ec0: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a ite3_backup is.*
2ed0: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 * finished. The
2ee0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 sqlite3_close_v
2ef0: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 2() interface is
2f00: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
2f10: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c e with.** host l
2f20: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 anguages that ar
2f30: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 e garbage collec
2f40: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 ted, and where t
2f50: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 he order in whic
2f60: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 h.** destructors
2f70: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 are called is a
2f80: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 rbitrary..**.**
2f90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f Applications sho
2fa0: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e uld [sqlite3_fin
2fb0: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 alize | finalize
2fc0: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 ] all [prepared
2fd0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 statements],.**
2fe0: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c [sqlite3_blob_cl
2ff0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c ose | close] all
3000: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c [BLOB handles],
3010: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 and .** [sqlite
3020: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 3_backup_finish
3030: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 | finish] all [s
3040: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
3050: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 bjects associate
3060: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 d.** with the [s
3070: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 qlite3] object p
3080: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 rior to attempti
3090: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 ng to close the
30a0: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 object. ^If.**
30b0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
30c0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 () is called on
30d0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
30e0: 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 ection] that sti
30f0: 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 ll has.** outsta
3100: 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 nding [prepared
3110: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c statements], [BL
3120: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 OB handles], and
3130: 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f /or.** [sqlite3_
3140: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 backup] objects
3150: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 then it returns
3160: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 [SQLITE_OK] and
3170: 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e the deallocation
3180: 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73 .** of resources
3190: 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74 is deferred unt
31a0: 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 il all [prepared
31b0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 statements], [B
31c0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a LOB handles],.**
31d0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 and [sqlite3_ba
31e0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 ckup] objects ar
31f0: 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 e also destroyed
3200: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b ..**.** ^If an [
3210: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
3220: 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 69 is destroyed whi
3230: 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e le a transaction
3240: 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 is open,.** the
3250: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
3260: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f automatically ro
3270: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a lled back..**.**
3280: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 The C parameter
3290: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f to [sqlite3_clo
32a0: 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 se(C)] and [sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d te3_close_v2(C)]
32c0: 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 .** must be eith
32d0: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 er a NULL.** poi
32e0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 nter or an [sqli
32f0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e te3] object poin
3300: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 ter obtained.**
3310: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 from [sqlite3_op
3320: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
3330: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a open16()], or.**
3340: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
3350: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 2()], and not pr
3360: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e eviously closed.
3370: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c .** ^Calling sql
3380: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 ite3_close() or
3390: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
33a0: 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 () with a NULL p
33b0: 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 ointer.** argume
33c0: 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 nt is a harmless
33d0: 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 no-op..*/.SQLIT
33e0: 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
33f0: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
3400: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 _close(sqlite3*)
3410: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
3420: 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
3440: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
3450: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 ** The type for
3460: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
3470: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 ion..** This is
3480: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 legacy and depre
3490: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e cated. It is in
34a0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f cluded for histo
34b0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 rical.** compati
34c0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f bility and is no
34d0: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f t documented..*/
34e0: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 .typedef int (*s
34f0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 qlite3_callback)
3500: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a (void*,int,char*
3510: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a *, char**);../*.
3520: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 ** CAPI3REF: One
3530: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 -Step Query Exec
3540: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a ution Interface.
3550: 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
3560: 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e3.**.** The sql
3570: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 ite3_exec() inte
3580: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 rface is a conve
3590: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 nience wrapper a
35a0: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 round.** [sqlite
35b0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
35c0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
35d0: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
35e0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 finalize()],.**
35f0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 that allows an a
3600: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 pplication to ru
3610: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 n multiple state
3620: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 ments of SQL.**
3630: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 without having t
3640: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 o use a lot of C
3650: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 code. .**.** ^T
3660: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
3670: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 ) interface runs
3680: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 zero or more UT
3690: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 F-8 encoded,.**
36a0: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 semicolon-separa
36b0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 te SQL statement
36c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 s passed into it
36d0: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a s 2nd argument,.
36e0: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 ** in the contex
36f0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 t of the [databa
3700: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 se connection] p
3710: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 assed in as its
3720: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 1st.** argument.
3730: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 ^If the callba
3740: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 ck function of t
3750: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 he 3rd argument
3760: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 to.** sqlite3_ex
3770: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c ec() is not NULL
3780: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 , then it is inv
3790: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 oked for each re
37a0: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 sult row.** comi
37b0: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 ng out of the ev
37c0: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 aluated SQL stat
37d0: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 ements. ^The 4t
37e0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a h argument to.**
37f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3800: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 is relayed throu
3810: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 gh to the 1st ar
3820: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a gument of each.*
3830: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 * callback invoc
3840: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 ation. ^If the
3850: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 callback pointer
3860: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 to sqlite3_exec
3870: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 ().** is NULL, t
3880: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 hen no callback
3890: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 is ever invoked
38a0: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 and result rows
38b0: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a are.** ignored..
38c0: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 **.** ^If an err
38d0: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 or occurs while
38e0: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 evaluating the S
38f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 QL statements pa
3900: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c ssed into.** sql
3910: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 ite3_exec(), the
3920: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 n execution of t
3930: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 he current state
3940: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a ment stops and.*
3950: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 * subsequent sta
3960: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 tements are skip
3970: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 ped. ^If the 5t
3980: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
3990: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
39a0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 is not NULL the
39b0: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 n any error mess
39c0: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 age is written i
39d0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 nto memory obtai
39e0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
39f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 ite3_malloc()] a
3a00: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 nd passed back t
3a10: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 hrough the 5th p
3a20: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 arameter..** To
3a30: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 avoid memory lea
3a40: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 ks, the applicat
3a50: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b ion should invok
3a60: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 e [sqlite3_free(
3a70: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d )].** on error m
3a80: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 essage strings r
3a90: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 eturned through
3aa0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
3ab0: 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 r of.** of sqlit
3ac0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 e3_exec() after
3ad0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
3ae0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c e string is no l
3af0: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a onger needed..**
3b00: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 ^If the 5th par
3b10: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3b20: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 3_exec() is not
3b30: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f NULL and no erro
3b40: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 rs.** occur, the
3b50: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 n sqlite3_exec()
3b60: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 sets the pointe
3b70: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 r in its 5th par
3b80: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c ameter to.** NUL
3b90: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 L before returni
3ba0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e ng..**.** ^If an
3bb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3bc0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
3bd0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 non-zero, the s
3be0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
3bf0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
3c00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 SQLITE_ABORT wi
3c10: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 thout invoking t
3c20: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 he callback agai
3c30: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 n and.** without
3c40: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 running any sub
3c50: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 sequent SQL stat
3c60: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ements..**.** ^T
3c70: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 he 2nd argument
3c80: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 to the sqlite3_e
3c90: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 xec() callback f
3ca0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a unction is the.*
3cb0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 * number of colu
3cc0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
3cd0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 t. ^The 3rd arg
3ce0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c ument to the sql
3cf0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 ite3_exec().** c
3d00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 allback is an ar
3d10: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
3d20: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 to strings obtai
3d30: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a ned as if from.*
3d40: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
3d50: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 n_text()], one f
3d60: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 or each column.
3d70: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 ^If an element
3d80: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 of a.** result r
3d90: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 ow is NULL then
3da0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
3db0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 g string pointer
3dc0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 for the.** sqli
3dd0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 te3_exec() callb
3de0: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ack is a NULL po
3df0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 inter. ^The 4th
3e00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
3e10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3e20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 () callback is a
3e30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
3e40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 ers to strings w
3e50: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 here each.** ent
3e60: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 ry represents th
3e70: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 e name of corres
3e80: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 ponding result c
3e90: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 olumn as obtaine
3ea0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
3eb0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
3ec0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 ]..**.** ^If the
3ed0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 2nd parameter t
3ee0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
3ef0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
3f00: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a er, a pointer.**
3f10: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 to an empty str
3f20: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 ing, or a pointe
3f30: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 r that contains
3f40: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 only whitespace
3f50: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 and/or .** SQL c
3f60: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f omments, then no
3f70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
3f80: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e are evaluated an
3f90: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a d the database.*
3fa0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 * is not changed
3fb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 ..**.** Restrict
3fc0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ions:.**.** <ul>
3fd0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 .** <li> The app
3fe0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e lication must in
3ff0: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 sure that the 1s
4000: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
4010: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
4020: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 is a valid
4030: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 and open [datab
4040: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
4050: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 .** <li> The app
4060: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f lication must no
4070: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 t close the [dat
4080: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
4090: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a ] specified by.*
40a0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 * the 1st p
40b0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
40c0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 te3_exec() while
40d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
40e0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c is running..** <
40f0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 li> The applicat
4100: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 ion must not mod
4110: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 ify the SQL stat
4120: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 ement text passe
4130: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 d into.** t
4140: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
4150: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 of sqlite3_exec
4160: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 () while sqlite3
4170: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 _exec() is runni
4180: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a ng..** </ul>.*/.
4190: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
41a0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
41b0: 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 lite3_exec(. sq
41c0: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 lite3*,
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41e0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f /* An o
41f0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a pen database */.
4200: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 const char *sq
4210: 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 l,
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
4230: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 SQL to be evalua
4240: 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 ted */. int (*c
4250: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 allback)(void*,i
4260: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a nt,char**,char**
4270: 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 ), /* Callback
4280: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f function */. vo
4290: 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 id *,
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
42b0: 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 /* 1st
42c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c argument to call
42d0: 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a back */. char *
42e0: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 *errmsg
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4300: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 /* Error ms
4310: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a g written here *
4320: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
4330: 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 3REF: Result Cod
4340: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
4350: 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 {result code def
4360: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 initions}.**.**
4370: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 Many SQLite func
4380: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 tions return an
4390: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 integer result c
43a0: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 ode from the set
43b0: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 shown.** here i
43c0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 n order to indic
43d0: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 ate success or f
43e0: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 ailure..**.** Ne
43f0: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 w error codes ma
4400: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
4410: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
4420: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 SQLite..**.** S
4430: 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 ee also: [extend
4440: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 ed result code d
4450: 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 efinitions].*/.#
4460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b define SQLITE_OK
4470: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 0 /
4480: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 * Successful res
4490: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e ult */./* beginn
44a0: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 ing-of-error-cod
44b0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 es */.#define SQ
44c0: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 LITE_ERROR
44d0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 1 /* SQL err
44e0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 or or missing da
44f0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e tabase */.#defin
4500: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 e SQLITE_INTERNA
4510: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 L 2 /* Int
4520: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f ernal logic erro
4530: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 r in SQLite */.#
4540: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 define SQLITE_PE
4550: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f RM 3 /
4560: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 * Access permiss
4570: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 ion denied */.#d
4580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f efine SQLITE_ABO
4590: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a RT 4 /*
45a0: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e Callback routin
45b0: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 e requested an a
45c0: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 bort */.#define
45d0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 SQLITE_BUSY
45e0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 5 /* The d
45f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 atabase file is
4600: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e locked */.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 e SQLITE_LOCKED
4620: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 6 /* A t
4630: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 able in the data
4640: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a base is locked *
4650: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4660: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 _NOMEM 7
4670: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 /* A malloc()
4680: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e failed */.#defin
4690: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
46a0: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 Y 8 /* Att
46b0: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 empt to write a
46c0: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 readonly databas
46d0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
46e0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 ITE_INTERRUPT
46f0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 9 /* Operatio
4700: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 n terminated by
4710: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
4720: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t()*/.#define SQ
4730: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 LITE_IOERR
4740: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 10 /* Some ki
4750: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 nd of disk I/O e
4760: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f rror occurred */
4770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4780: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 CORRUPT 11
4790: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
47a0: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d disk image is m
47b0: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 alformed */.#def
47c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f ine SQLITE_NOTFO
47d0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 UND 12 /* U
47e0: 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e nknown opcode in
47f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f sqlite3_file_co
4800: 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 ntrol() */.#defi
4810: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 ne SQLITE_FULL
4820: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 13 /* In
4830: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 sertion failed b
4840: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 ecause database
4850: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 is full */.#defi
4860: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 ne SQLITE_CANTOP
4870: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e EN 14 /* Un
4880: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 able to open the
4890: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a database file *
48a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
48b0: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 _PROTOCOL 15
48c0: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f /* Database lo
48d0: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f ck protocol erro
48e0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
48f0: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 ITE_EMPTY
4900: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 16 /* Database
4910: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 is empty */.#de
4920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 fine SQLITE_SCHE
4930: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 MA 17 /*
4940: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 The database sch
4950: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 ema changed */.#
4960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f define SQLITE_TO
4970: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f OBIG 18 /
4980: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 * String or BLOB
4990: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 exceeds size li
49a0: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 mit */.#define S
49b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
49c0: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 19 /* Abort
49d0: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e due to constrain
49e0: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 t violation */.#
49f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 define SQLITE_MI
4a00: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f SMATCH 20 /
4a10: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d * Data type mism
4a20: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 atch */.#define
4a30: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 SQLITE_MISUSE
4a40: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 21 /* Libra
4a50: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 ry used incorrec
4a60: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 tly */.#define S
4a70: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 QLITE_NOLFS
4a80: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 22 /* Uses O
4a90: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 S features not s
4aa0: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 upported on host
4ab0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4ac0: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 TE_AUTH 2
4ad0: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 3 /* Authoriza
4ae0: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 tion denied */.#
4af0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f define SQLITE_FO
4b00: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f RMAT 24 /
4b10: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 * Auxiliary data
4b20: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f base format erro
4b30: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
4b40: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 ITE_RANGE
4b50: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 25 /* 2nd para
4b60: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
4b70: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e _bind out of ran
4b80: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ge */.#define SQ
4b90: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 LITE_NOTADB
4ba0: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 26 /* File op
4bb0: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 ened that is not
4bc0: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
4bd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4be0: 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32 TE_NOTICE 2
4bf0: 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 7 /* Notificat
4c00: 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 ions from sqlite
4c10: 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 3_log() */.#defi
4c20: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e ne SQLITE_WARNIN
4c30: 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61 G 28 /* Wa
4c40: 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 rnings from sqli
4c50: 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 te3_log() */.#de
4c60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 fine SQLITE_ROW
4c70: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 100 /*
4c80: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 sqlite3_step() h
4c90: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 as another row r
4ca0: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 eady */.#define
4cb0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 SQLITE_DONE
4cc0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 101 /* sqlit
4cd0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 e3_step() has fi
4ce0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 nished executing
4cf0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 */./* end-of-er
4d00: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a ror-codes */../*
4d10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 .** CAPI3REF: Ex
4d20: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f tended Result Co
4d30: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a des.** KEYWORDS:
4d40: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c {extended resul
4d50: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f t code definitio
4d60: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 ns}.**.** In its
4d70: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
4d80: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 ration, SQLite A
4d90: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 PI routines retu
4da0: 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74 rn one of 30 int
4db0: 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 eger.** [result
4dc0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 codes]. However
4dd0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 , experience has
4de0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 shown that many
4df0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 of.** these res
4e00: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f ult codes are to
4e10: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 o coarse-grained
4e20: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 . They do not p
4e30: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 rovide as.** muc
4e40: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 h information ab
4e50: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 out problems as
4e60: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 programmers migh
4e70: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 t like. In an e
4e80: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 ffort to.** addr
4e90: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 ess this, newer
4ea0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
4eb0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e te (version 3.3.
4ec0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 8 and later) inc
4ed0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 lude.** support
4ee0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 for additional r
4ef0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 esult codes that
4f00: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 provide more de
4f10: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 tailed informati
4f20: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f on.** about erro
4f30: 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74 65 6e rs. These [exten
4f40: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
4f50: 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 ] are enabled or
4f60: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 disabled.** on
4f70: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63 a per database c
4f80: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 onnection basis
4f90: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 using the.** [sq
4fa0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 lite3_extended_r
4fb0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 esult_codes()] A
4fc0: 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 74 PI. Or, the ext
4fd0: 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a ended code for.*
4fe0: 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e * the most recen
4ff0: 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65 20 6f t error can be o
5000: 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a btained using.**
5010: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 [sqlite3_extend
5020: 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a ed_errcode()]..*
5030: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5040: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 _IOERR_READ
5050: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5060: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 _IOERR | (1<<8))
5070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5080: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 IOERR_SHORT_READ
5090: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
50a0: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a IOERR | (2<<8)).
50b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
50c0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 OERR_WRITE
50d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
50e0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 OERR | (3<<8)).#
50f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5100: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 ERR_FSYNC
5110: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5120: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 ERR | (4<<8)).#d
5130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5140: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 RR_DIR_FSYNC
5150: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5160: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 RR | (5<<8)).#de
5170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
5180: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 R_TRUNCATE
5190: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
51a0: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 R | (6<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
51c0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 _FSTAT
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
51e0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 | (7<<8)).#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5200: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 UNLOCK
5210: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5220: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (8<<8)).#defin
5230: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 e SQLITE_IOERR_R
5240: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 DLOCK
5250: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5260: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (9<<8)).#define
5270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 SQLITE_IOERR_DE
5280: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
5290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
52a0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (10<<8)).#define
52b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c SQLITE_IOERR_BL
52c0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 OCKED
52d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
52e0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (11<<8)).#define
52f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f SQLITE_IOERR_NO
5300: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 MEM
5310: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5320: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (12<<8)).#define
5330: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 SQLITE_IOERR_AC
5340: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 CESS
5350: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5360: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (13<<8)).#define
5370: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 SQLITE_IOERR_CH
5380: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 ECKRESERVEDLOCK
5390: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
53a0: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (14<<8)).#define
53b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f SQLITE_IOERR_LO
53c0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CK
53d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
53e0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (15<<8)).#define
53f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c SQLITE_IOERR_CL
5400: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 OSE
5410: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5420: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (16<<8)).#define
5430: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 SQLITE_IOERR_DI
5440: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 R_CLOSE
5450: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5460: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (17<<8)).#define
5470: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
5480: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 MOPEN
5490: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
54a0: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (18<<8)).#define
54b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
54c0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 MSIZE
54d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
54e0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (19<<8)).#define
54f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
5500: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 MLOCK
5510: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5520: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (20<<8)).#define
5530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
5540: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 MMAP
5550: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5560: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (21<<8)).#define
5570: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 SQLITE_IOERR_SE
5580: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 EK
5590: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
55a0: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (22<<8)).#define
55b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 SQLITE_IOERR_DE
55c0: 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 LETE_NOENT
55d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
55e0: 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (23<<8)).#define
55f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d SQLITE_IOERR_MM
5600: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AP
5610: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5620: 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (24<<8)).#define
5630: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 SQLITE_IOERR_GE
5640: 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 TTEMPPATH
5650: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5660: 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (25<<8)).#define
5670: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f SQLITE_IOERR_CO
5680: 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20 NVPATH
5690: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
56a0: 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (26<<8)).#define
56b0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 SQLITE_LOCKED_S
56c0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 HAREDCACHE
56d0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c (SQLITE_LOCKED |
56e0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (1<<8)).#defin
56f0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 e SQLITE_BUSY_RE
5700: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 COVERY
5710: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 (SQLITE_BUSY
5720: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
5730: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 ne SQLITE_BUSY_S
5740: 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 NAPSHOT
5750: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 (SQLITE_BUSY
5760: 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 | (2<<8)).#def
5770: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
5780: 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 PEN_NOTEMPDIR
5790: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f (SQLITE_CANTO
57a0: 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 PEN | (1<<8)).#d
57b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
57c0: 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 TOPEN_ISDIR
57d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e (SQLITE_CAN
57e0: 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a TOPEN | (2<<8)).
57f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5800: 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 ANTOPEN_FULLPATH
5810: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
5820: 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 ANTOPEN | (3<<8)
5830: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5840: 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 _CANTOPEN_CONVPA
5850: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 TH (SQLITE
5860: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c _CANTOPEN | (4<<
5870: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5880: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 TE_CORRUPT_VTAB
5890: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
58a0: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c TE_CORRUPT | (1<
58b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
58c0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 ITE_READONLY_REC
58d0: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c OVERY (SQL
58e0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 ITE_READONLY | (
58f0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5900: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 QLITE_READONLY_C
5910: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 ANTLOCK (S
5920: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c QLITE_READONLY |
5930: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
5940: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 SQLITE_READONLY
5950: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 _ROLLBACK
5960: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 (SQLITE_READONLY
5970: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 | (3<<8)).#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e ne SQLITE_READON
5990: 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20 LY_DBMOVED
59a0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e (SQLITE_READON
59b0: 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 LY | (4<<8)).#de
59c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 fine SQLITE_ABOR
59d0: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 T_ROLLBACK
59e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 (SQLITE_ABOR
59f0: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 T | (2<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5a10: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 RAINT_CHECK
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5a30: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a RAINT | (1<<8)).
5a40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5a50: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 ONSTRAINT_COMMIT
5a60: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 HOOK (SQLITE_C
5a70: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c ONSTRAINT | (2<<
5a80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5a90: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f TE_CONSTRAINT_FO
5aa0: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 REIGNKEY (SQLI
5ab0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5ac0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (3<<8)).#define
5ad0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5ae0: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 T_FUNCTION (
5af0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5b00: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 T | (4<<8)).#def
5b10: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5b20: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 RAINT_NOTNULL
5b30: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5b40: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a RAINT | (5<<8)).
5b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5b60: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 ONSTRAINT_PRIMAR
5b70: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 YKEY (SQLITE_C
5b80: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c ONSTRAINT | (6<<
5b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5ba0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 TE_CONSTRAINT_TR
5bb0: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 IGGER (SQLI
5bc0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5bd0: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (7<<8)).#define
5be0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5bf0: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 T_UNIQUE (
5c00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5c10: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 T | (8<<8)).#def
5c20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5c30: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 RAINT_VTAB
5c40: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5c50: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a RAINT | (9<<8)).
5c60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5c70: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 ONSTRAINT_ROWID
5c80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
5c90: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c ONSTRAINT |(10<<
5ca0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5cb0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 TE_NOTICE_RECOVE
5cc0: 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49 R_WAL (SQLI
5cd0: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c TE_NOTICE | (1<<
5ce0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5cf0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 TE_NOTICE_RECOVE
5d00: 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 R_ROLLBACK (SQLI
5d10: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c TE_NOTICE | (2<<
5d20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5d30: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 TE_WARNING_AUTOI
5d40: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49 NDEX (SQLI
5d50: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c TE_WARNING | (1<
5d60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5d70: 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20 20 ITE_AUTH_USER
5d80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5d90: 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 ITE_AUTH | (1<<8
5da0: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ))../*.** CAPI3R
5db0: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 EF: Flags For Fi
5dc0: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f le Open Operatio
5dd0: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 ns.**.** These b
5de0: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e it values are in
5df0: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
5e00: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 n the.** 3rd par
5e10: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ameter to the [s
5e20: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
5e30: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a ] interface and.
5e40: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 ** in the 4th pa
5e50: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b rameter to the [
5e60: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 sqlite3_vfs.xOpe
5e70: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 n] method..*/.#d
5e80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5e90: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 N_READONLY
5ea0: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 0x00000001 /
5eb0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
5ec0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
5ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5ee0: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 N_READWRITE
5ef0: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 0x00000002 /
5f00: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
5f10: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
5f20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5f30: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 N_CREATE
5f40: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 0x00000004 /
5f50: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
5f60: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5f80: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 N_DELETEONCLOSE
5f90: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 0x00000008 /
5fa0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
5fb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5fc0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 N_EXCLUSIVE
5fd0: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 0x00000010 /
5fe0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
5ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6000: 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 N_AUTOPROXY
6010: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 0x00000020 /
6020: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6040: 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 N_URI
6050: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 0x00000040 /
6060: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
6070: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
6080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6090: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 N_MEMORY
60a0: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 0x00000080 /
60b0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
60c0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
60d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
60e0: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 N_MAIN_DB
60f0: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 0x00000100 /
6100: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6120: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 N_TEMP_DB
6130: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 0x00000200 /
6140: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6150: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6160: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 N_TRANSIENT_DB
6170: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 0x00000400 /
6180: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
61a0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 N_MAIN_JOURNAL
61b0: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 0x00000800 /
61c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
61e0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 N_TEMP_JOURNAL
61f0: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 0x00001000 /
6200: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6220: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 N_SUBJOURNAL
6230: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 0x00002000 /
6240: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6260: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c N_MASTER_JOURNAL
6270: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 0x00004000 /
6280: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6290: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
62a0: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 N_NOMUTEX
62b0: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 0x00008000 /
62c0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
62d0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
62e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
62f0: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 N_FULLMUTEX
6300: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 0x00010000 /
6310: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
6320: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
6330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6340: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 N_SHAREDCACHE
6350: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 0x00020000 /
6360: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
6370: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
6380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6390: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 N_PRIVATECACHE
63a0: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 0x00040000 /
63b0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
63c0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
63d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
63e0: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 N_WAL
63f0: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 0x00080000 /
6400: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f * VFS only */../
6410: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 * Reserved:
6420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6430: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 0x00F00000 *
6440: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
6450: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 F: Device Charac
6460: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 teristics.**.**
6470: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 The xDeviceChara
6480: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f cteristics metho
6490: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 d of the [sqlite
64a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 3_io_methods].**
64b0: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 object returns
64c0: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 an integer which
64d0: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 is a vector of
64e0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c these.** bit val
64f0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 ues expressing I
6500: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 /O characteristi
6510: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 cs of the mass s
6520: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 torage.** device
6530: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 that holds the
6540: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 file that the [s
6550: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
6560: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e s].** refers to.
6570: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
6580: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
6590: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
65a0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
65b0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
65c0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
65d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
65e0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
65f0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
6600: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
6610: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
6620: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
6630: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
6640: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
6650: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
6660: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
6670: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
6680: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
6690: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
66a0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
66b0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
66c0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
66d0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
66e0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
66f0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
6700: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
6710: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
6720: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
6730: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6740: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
6750: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
6760: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
6770: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
6780: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
6790: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
67a0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 to xWrite(). T
67b0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
67c0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
67d0: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 ITE property mea
67e0: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 ns that.** after
67f0: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e reboot followin
6800: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 g a crash or pow
6810: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c er loss, the onl
6820: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 y bytes in a.**
6830: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 file that were w
6840: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 ritten at the ap
6850: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 plication level
6860: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 might have chang
6870: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 ed.** and that a
6880: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 djacent bytes, e
6890: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e ven bytes within
68a0: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 the same sector
68b0: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 are.** guarante
68c0: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 ed to be unchang
68d0: 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f ed. The SQLITE_
68e0: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c IOCAP_UNDELETABL
68f0: 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 E_WHEN_OPEN.** f
6900: 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61 lag indicate tha
6910: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 t a file cannot
6920: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 be deleted when
6930: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 open. The.** SQ
6940: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 LITE_IOCAP_IMMUT
6950: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 ABLE flag indica
6960: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c tes that the fil
6970: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d e is on.** read-
6980: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 only media and c
6990: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 annot be changed
69a0: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 even by process
69b0: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 es with.** eleva
69c0: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a ted privileges..
69d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
69e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 E_IOCAP_ATOMIC
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
6a00: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e x00000001.#defin
6a10: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6a20: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 TOMIC512
6a30: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
6a40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6a50: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 IOCAP_ATOMIC1K
6a60: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6a70: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 0000004.#define
6a80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6a90: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 MIC2K
6aa0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 0x00000008.#
6ab0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6ac0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 CAP_ATOMIC4K
6ad0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6ae0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 00010.#define SQ
6af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6b00: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C8K
6b10: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 0x00000020.#de
6b20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6b30: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 P_ATOMIC16K
6b40: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6b50: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 040.#define SQLI
6b60: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 TE_IOCAP_ATOMIC3
6b70: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2K
6b80: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 0x00000080.#defi
6b90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6ba0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 ATOMIC64K
6bb0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 0x0000010
6bc0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
6bd0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
6be0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 ND 0x
6bf0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 00000200.#define
6c00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
6c10: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 QUENTIAL
6c20: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0x00000400.
6c30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6c40: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 OCAP_UNDELETABLE
6c50: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 _WHEN_OPEN 0x00
6c60: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 000800.#define S
6c70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
6c80: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 RSAFE_OVERWRITE
6c90: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 0x00001000.#d
6ca0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
6cb0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 AP_IMMUTABLE
6cc0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
6cd0: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 2000../*.** CAPI
6ce0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 3REF: File Locki
6cf0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 ng Levels.**.**
6d00: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 SQLite uses one
6d10: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 of these integer
6d20: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
6d30: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e econd.** argumen
6d40: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 t to calls it ma
6d50: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b kes to the xLock
6d60: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 () and xUnlock()
6d70: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 methods.** of a
6d80: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 n [sqlite3_io_me
6d90: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a thods] object..*
6da0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6db0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 _LOCK_NONE
6dc0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
6dd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
6de0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
6df0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 e SQLITE_LOCK_RE
6e00: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 SERVED 2.#d
6e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
6e20: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 K_PENDING
6e30: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
6e40: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 _LOCK_EXCLUSIVE
6e50: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 4../*.** CAP
6e60: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 I3REF: Synchroni
6e70: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 zation Type Flag
6e80: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c s.**.** When SQL
6e90: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 ite invokes the
6ea0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f xSync() method o
6eb0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 f an.** [sqlite3
6ec0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
6ed0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f ect it uses a co
6ee0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 mbination of.**
6ef0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 these integer va
6f00: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f lues as the seco
6f10: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
6f20: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 ** When the SQLI
6f30: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
6f40: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 flag is used, i
6f50: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 t means that the
6f60: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 .** sync operati
6f70: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f on only needs to
6f80: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d flush data to m
6f90: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e ass storage. In
6fa0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 ode.** informati
6fb0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 on need not be f
6fc0: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c lushed. If the l
6fd0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f ower four bits o
6fe0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 f the flag.** eq
6ff0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ual SQLITE_SYNC_
7000: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 NORMAL, that mea
7010: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c ns to use normal
7020: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 fsync() semanti
7030: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f cs..** If the lo
7040: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 wer four bits eq
7050: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ual SQLITE_SYNC_
7060: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 FULL, that means
7070: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f .** to use Mac O
7080: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 S X style fullsy
7090: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 nc instead of fs
70a0: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 ync()..**.** Do
70b0: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 not confuse the
70c0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
70d0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 AL and SQLITE_SY
70e0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a NC_FULL flags.**
70f0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d with the [PRAGM
7100: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e A synchronous]=N
7110: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d ORMAL and [PRAGM
7120: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 A synchronous]=F
7130: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e ULL.** settings.
7140: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f The [synchrono
7150: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 us pragma] deter
7160: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 mines when calls
7170: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 to the.** xSync
7180: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 VFS method occu
7190: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e r and applies un
71a0: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 iformly across a
71b0: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a ll platforms..**
71c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 The SQLITE_SYNC
71d0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 _NORMAL and SQLI
71e0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 TE_SYNC_FULL fla
71f0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 gs determine how
7200: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 .** energetic or
7210: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 rigorous or for
7220: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f ceful the sync o
7230: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e perations are an
7240: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 d.** only make a
7250: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d difference on M
7260: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 ac OSX for the d
7270: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f efault SQLite co
7280: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 de..** (Third-pa
7290: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e rty VFS implemen
72a0: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c tations might al
72b0: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 so make the dist
72c0: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 inction.** betwe
72d0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e en SQLITE_SYNC_N
72e0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 ORMAL and SQLITE
72f0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 _SYNC_FULL, but
7300: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 among the.** ope
7310: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e rating systems n
7320: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 atively supporte
7330: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c d by SQLite, onl
7340: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 y Mac OSX.** car
7350: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 es about the dif
7360: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 ference.).*/.#de
7370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 fine SQLITE_SYNC
7380: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 _NORMAL 0
7390: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 x00002.#define S
73a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 QLITE_SYNC_FULL
73b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0x00003
73c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
73d0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 SYNC_DATAONLY
73e0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 0x00010../*.*
73f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
7400: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 nterface Open Fi
7410: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 le Handle.**.**
7420: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 An [sqlite3_file
7430: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 ] object represe
7440: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 nts an open file
7450: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c in the .** [sql
7460: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e ite3_vfs | OS in
7470: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 terface layer].
7480: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 Individual OS i
7490: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c nterface.** impl
74a0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c ementations will
74b0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 .** want to subc
74c0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 lass this object
74d0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 by appending ad
74e0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a ditional fields.
74f0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e ** for their own
7500: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 use. The pMeth
7510: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 ods entry is a p
7520: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
7530: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
7540: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 ods] object that
7550: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 defines methods
7560: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a for performing.
7570: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e ** I/O operation
7580: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 s on the open fi
7590: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 le..*/.typedef s
75a0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 truct sqlite3_fi
75b0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b le sqlite3_file;
75c0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
75d0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 file {. const s
75e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
75f0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f _methods *pMetho
7600: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 ds; /* Methods
7610: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 for an open file
7620: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
7630: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
7640: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 face File Virtua
7650: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 l Methods Object
7660: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c .**.** Every fil
7670: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 e opened by the
7680: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
7690: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c en] method popul
76a0: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 ates an.** [sqli
76b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
76c0: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f (or, more commo
76d0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 nly, a subclass
76e0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
76f0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 e3_file] object)
7700: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
7710: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
7720: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a f this object..*
7730: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 * This object de
7740: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 fines the method
7750: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 s used to perfor
7760: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 m various operat
7770: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 ions.** against
7780: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 the open file re
7790: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 presented by the
77a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
77b0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 object..**.** If
77c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
77d0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 s.xOpen] method
77e0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 sets the sqlite3
77f0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 _file.pMethods e
7800: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 lement .** to a
7810: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
7820: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 , then the sqlit
7830: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 e3_io_methods.xC
7840: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d lose method.** m
7850: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 ay be invoked ev
7860: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 en if the [sqlit
7870: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 e3_vfs.xOpen] re
7880: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 ported that it f
7890: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f ailed. The.** o
78a0: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 nly way to preve
78b0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c nt a call to xCl
78c0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 ose following a
78d0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f failed [sqlite3_
78e0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 vfs.xOpen].** is
78f0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 for the [sqlite
7900: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 3_vfs.xOpen] to
7910: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f set the sqlite3_
7920: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c file.pMethods el
7930: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c ement.** to NULL
7940: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
7950: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 s argument to xS
7960: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f ync may be one o
7970: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e f [SQLITE_SYNC_N
7980: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 ORMAL] or.** [SQ
7990: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e LITE_SYNC_FULL].
79a0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 The first choi
79b0: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c ce is the normal
79c0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 fsync()..** The
79d0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 second choice i
79e0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 s a Mac OS X sty
79f0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 le fullsync. Th
7a00: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 e [SQLITE_SYNC_D
7a10: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 ATAONLY].** flag
7a20: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 may be ORed in
7a30: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 to indicate that
7a40: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f only the data o
7a50: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e f the file.** an
7a60: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 d not its inode
7a70: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 needs to be sync
7a80: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e ed..**.** The in
7a90: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 teger values to
7aa0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c xLock() and xUnl
7ab0: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 ock() are one of
7ac0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
7ad0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
7ae0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 NE],.** <li> [SQ
7af0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
7b00: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
7b10: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 TE_LOCK_RESERVED
7b20: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
7b30: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d TE_LOCK_PENDING]
7b40: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 , or.** <li> [SQ
7b50: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
7b60: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a IVE]..** </ul>.*
7b70: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 * xLock() increa
7b80: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 ses the lock. xU
7b90: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 nlock() decrease
7ba0: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 s the lock..** T
7bb0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 he xCheckReserve
7bc0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 dLock() method c
7bd0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e hecks whether an
7be0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 y database conne
7bf0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 ction,.** either
7c00: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 in this process
7c10: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 or in some othe
7c20: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f r process, is ho
7c30: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 lding a RESERVED
7c40: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 ,.** PENDING, or
7c50: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 EXCLUSIVE lock
7c60: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 on the file. It
7c70: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a returns true.**
7c80: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 if such a lock
7c90: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 exists and false
7ca0: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a otherwise..**.*
7cb0: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 * The xFileContr
7cc0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 ol() method is a
7cd0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 generic interfa
7ce0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 ce that allows c
7cf0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 ustom.** VFS imp
7d00: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 lementations to
7d10: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c directly control
7d20: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 an open file us
7d30: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
7d40: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
7d50: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ()] interface.
7d60: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 The second "op"
7d70: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a argument is an.*
7d80: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 * integer opcode
7d90: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 . The third arg
7da0: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 ument is a gener
7db0: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e ic pointer inten
7dc0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 ded to.** point
7dd0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 to a structure t
7de0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 hat may contain
7df0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 arguments or spa
7e00: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a ce in which to.*
7e10: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 * write return v
7e20: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 alues. Potentia
7e30: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 l uses for xFile
7e40: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 Control() might
7e50: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 be.** functions
7e60: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 to enable blocki
7e70: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 ng locks with ti
7e80: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 meouts, to chang
7e90: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 e the.** locking
7ea0: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 strategy (for e
7eb0: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f xample to use do
7ec0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 t-file locks), t
7ed0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f o inquire.** abo
7ee0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 ut the status of
7ef0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 a lock, or to b
7f00: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 reak stale locks
7f10: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a . The SQLite.**
7f20: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 core reserves a
7f30: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 ll opcodes less
7f40: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 than 100 for its
7f50: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b own use..** A [
7f60: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 file control opc
7f70: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f odes | list of o
7f80: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 pcodes] less tha
7f90: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 n 100 is availab
7fa0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 le..** Applicati
7fb0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 ons that define
7fc0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f a custom xFileCo
7fd0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f ntrol method sho
7fe0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a uld use opcodes.
7ff0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 ** greater than
8000: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 100 to avoid con
8010: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 flicts. VFS imp
8020: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
8030: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 uld.** return [S
8040: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 QLITE_NOTFOUND]
8050: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c for file control
8060: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 opcodes that th
8070: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 ey do not.** rec
8080: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 ognize..**.** Th
8090: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 e xSectorSize()
80a0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 method returns t
80b0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f he sector size o
80c0: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 f the.** device
80d0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 that underlies t
80e0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 he file. The se
80f0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 ctor size is the
8100: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 .** minimum writ
8110: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 e that can be pe
8120: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 rformed without
8130: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 disturbing.** ot
8140: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 her bytes in the
8150: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 file. The xDev
8160: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
8170: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 cs().** method r
8180: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 eturns a bit vec
8190: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 tor describing b
81a0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a ehaviors of the.
81b0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 ** underlying de
81c0: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e vice:.**.** <ul>
81d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
81e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a _IOCAP_ATOMIC].*
81f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
8200: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a OCAP_ATOMIC512].
8210: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8220: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a IOCAP_ATOMIC1K].
8230: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8240: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a IOCAP_ATOMIC2K].
8250: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8260: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a IOCAP_ATOMIC4K].
8270: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8280: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a IOCAP_ATOMIC8K].
8290: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
82a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d IOCAP_ATOMIC16K]
82b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
82c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b _IOCAP_ATOMIC32K
82d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
82e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 E_IOCAP_ATOMIC64
82f0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
8300: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
8310: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 PEND].** <li> [S
8320: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
8330: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e ENTIAL].** </ul>
8340: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
8350: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
8360: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
8370: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
8380: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
8390: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
83a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
83b0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
83c0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
83d0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
83e0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
83f0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
8400: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
8410: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
8420: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
8430: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
8440: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
8450: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
8460: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
8470: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
8480: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
8490: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
84a0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
84b0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
84c0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
84d0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
84e0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
84f0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
8500: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
8510: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
8520: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
8530: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
8540: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
8550: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
8560: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
8570: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a to xWrite()..**
8580: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 .** If xRead() r
8590: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f eturns SQLITE_IO
85a0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 ERR_SHORT_READ i
85b0: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c t must also fill
85c0: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 .** in the unrea
85d0: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 d portions of th
85e0: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 e buffer with ze
85f0: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 ros. A VFS that
8600: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 .** fails to zer
8610: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
8620: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f ds might seem to
8630: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c work. However,
8640: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a .** failure to z
8650: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 ero-fill short r
8660: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 eads will eventu
8670: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 ally lead to.**
8680: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 database corrupt
8690: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
86a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
86b0: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 o_methods sqlite
86c0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 3_io_methods;.st
86d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
86e0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 methods {. int
86f0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 iVersion;. int
8700: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 (*xClose)(sqlite
8710: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
8720: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 (*xRead)(sqlite3
8730: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 _file*, void*, i
8740: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 nt iAmt, sqlite3
8750: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 _int64 iOfst);.
8760: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 int (*xWrite)(s
8770: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f qlite3_file*, co
8780: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 nst void*, int i
8790: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 Amt, sqlite3_int
87a0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 64 iOfst);. int
87b0: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 (*xTruncate)(sq
87c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c lite3_file*, sql
87d0: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 ite3_int64 size)
87e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 ;. int (*xSync)
87f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8800: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e int flags);. in
8810: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 t (*xFileSize)(s
8820: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
8830: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 lite3_int64 *pSi
8840: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f ze);. int (*xLo
8850: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
8860: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
8870: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 *xUnlock)(sqlite
8880: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
8890: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 int (*xCheckRes
88a0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 ervedLock)(sqlit
88b0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 e3_file*, int *p
88c0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 ResOut);. int (
88d0: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 *xFileControl)(s
88e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
88f0: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 t op, void *pArg
8900: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 );. int (*xSect
8910: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f orSize)(sqlite3_
8920: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
8930: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
8940: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f istics)(sqlite3_
8950: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 file*);. /* Met
8960: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 hods above are v
8970: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e alid for version
8980: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 1 */. int (*xS
8990: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 hmMap)(sqlite3_f
89a0: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 ile*, int iPg, i
89b0: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f nt pgsz, int, vo
89c0: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a id volatile**);.
89d0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b int (*xShmLock
89e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
89f0: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 int offset, int
8a00: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a n, int flags);.
8a10: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 void (*xShmBar
8a20: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 rier)(sqlite3_fi
8a30: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 le*);. int (*xS
8a40: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 hmUnmap)(sqlite3
8a50: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 _file*, int dele
8a60: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 teFlag);. /* Me
8a70: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
8a80: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f valid for versio
8a90: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 n 2 */. int (*x
8aa0: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 Fetch)(sqlite3_f
8ab0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
8ac0: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 t64 iOfst, int i
8ad0: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b Amt, void **pp);
8ae0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 . int (*xUnfetc
8af0: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a h)(sqlite3_file*
8b00: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
8b10: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b iOfst, void *p);
8b20: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 . /* Methods ab
8b30: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f ove are valid fo
8b40: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 r version 3 */.
8b50: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d /* Additional m
8b60: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 ethods may be ad
8b70: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
8b80: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a leases */.};../*
8b90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 .** CAPI3REF: St
8ba0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 andard File Cont
8bb0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b rol Opcodes.** K
8bc0: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 EYWORDS: {file c
8bd0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 ontrol opcodes}
8be0: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 {file control op
8bf0: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 code}.**.** Thes
8c00: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
8c10: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 nts are opcodes
8c20: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e for the xFileCon
8c30: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f trol method.** o
8c40: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 f the [sqlite3_i
8c50: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
8c60: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 t and for the [s
8c70: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
8c80: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 rol()].** interf
8c90: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ace..**.** <ul>.
8ca0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
8cb0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d FCNTL_LOCKSTATE]
8cc0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
8cd0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
8ce0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
8cf0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 for debugging.
8d00: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 This.** opcode
8d10: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 causes the xFile
8d20: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 Control method t
8d30: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 o write the curr
8d40: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 ent state of.**
8d50: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 the lock (one of
8d60: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
8d70: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 NE], [SQLITE_LOC
8d80: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 K_SHARED],.** [S
8d90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
8da0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f VED], [SQLITE_LO
8db0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 CK_PENDING], or
8dc0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
8dd0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f LUSIVE]).** into
8de0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 an integer that
8df0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 the pArg argume
8e00: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 nt points to. Th
8e10: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a is capability.**
8e20: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 is used during
8e30: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f testing and is o
8e40: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 nly available wh
8e50: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 en the SQLITE_TE
8e60: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 ST.** compile-ti
8e70: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 me option is use
8e80: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 d..**.** <li>[[S
8e90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 QLITE_FCNTL_SIZE
8ea0: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b _HINT]].** The [
8eb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a SQLITE_FCNTL_SIZ
8ec0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 E_HINT] opcode i
8ed0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 s used by SQLite
8ee0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 to give the VFS
8ef0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 .** layer a hint
8f00: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 of how large th
8f10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
8f20: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 will grow to be
8f30: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 during the.** cu
8f40: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f rrent transactio
8f50: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 n. This hint is
8f60: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 not guaranteed
8f70: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 to be accurate b
8f80: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 ut it.** is ofte
8f90: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e n close. The un
8fa0: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 derlying VFS mig
8fb0: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 ht choose to pre
8fc0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 allocate databas
8fd0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 e.** file space
8fe0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 based on this hi
8ff0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 nt in order to h
9000: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 elp writes to th
9010: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 e database.** fi
9020: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a le run faster..*
9030: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9040: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 E_FCNTL_CHUNK_SI
9050: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ZE]].** The [SQL
9060: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f ITE_FCNTL_CHUNK_
9070: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 SIZE] opcode is
9080: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 used to request
9090: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 that the VFS.**
90a0: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e extends and trun
90b0: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 cates the databa
90c0: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b se file in chunk
90d0: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 s of a size spec
90e0: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 ified.** by the
90f0: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 user. The fourth
9100: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
9110: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
9120: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a ol()] should .**
9130: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 point to an int
9140: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 eger (type int)
9150: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e containing the n
9160: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f ew chunk-size to
9170: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 use.** for the
9180: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 nominated databa
9190: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 se. Allocating d
91a0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 atabase file spa
91b0: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 ce in large.** c
91c0: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 hunks (say 1MB a
91d0: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 t a time), may r
91e0: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 educe file-syste
91f0: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 m fragmentation
9200: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 and.** improve p
9210: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f erformance on so
9220: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a me systems..**.*
9230: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
9240: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 CNTL_FILE_POINTE
9250: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 R]].** The [SQLI
9260: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
9270: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 INTER] opcode is
9280: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 used to obtain
9290: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
92a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
92b0: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 e] object associ
92c0: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 ated with a part
92d0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a icular database.
92e0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 ** connection.
92f0: 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 See the [sqlite3
9300: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
9310: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 documentation f
9320: 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c or.** additional
9330: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
9340: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
9350: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 _FCNTL_SYNC_OMIT
9360: 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 TED]].** No long
9370: 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a er in use..**.**
9380: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
9390: 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 NTL_SYNC]].** Th
93a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
93b0: 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 SYNC] opcode is
93c0: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e generated intern
93d0: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 ally by SQLite a
93e0: 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 nd.** sent to th
93f0: 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c e VFS immediatel
9400: 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 y before the xSy
9410: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 nc method is inv
9420: 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 oked on a.** dat
9430: 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 abase file descr
9440: 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 iptor. Or, if th
9450: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 e xSync method i
9460: 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a s not invoked .*
9470: 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73 * because the us
9480: 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 er has configure
9490: 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a d SQLite with .*
94a0: 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 * [PRAGMA synchr
94b0: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 onous | PRAGMA s
94c0: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 ynchronous=OFF]
94d0: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e it is invoked in
94e0: 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 place .** of th
94f0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 e xSync method.
9500: 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 In most cases, t
9510: 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d he pointer argum
9520: 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a ent passed with.
9530: 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e ** this file-con
9540: 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f trol is NULL. Ho
9550: 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 wever, if the da
9560: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 tabase file is b
9570: 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 eing synced.** a
9580: 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 s part of a mult
9590: 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 i-database commi
95a0: 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 t, the argument
95b0: 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d points to a nul-
95c0: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 terminated.** st
95d0: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ring containing
95e0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 the transactions
95f0: 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 master-journal
9600: 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 file name. VFSes
9610: 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 that .** do not
9620: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 need this signa
9630: 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c l should silentl
9640: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 y ignore this op
9650: 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f code. Applicatio
9660: 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f ns .** should no
9670: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f t call [sqlite3_
9680: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
9690: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 with this opcode
96a0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 as doing so may
96b0: 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 .** disrupt the
96c0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 operation of th
96d0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 e specialized VF
96e0: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 Ses that do requ
96f0: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 ire it. .**.**
9700: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
9710: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 TL_COMMIT_PHASET
9720: 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c WO]].** The [SQL
9730: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 ITE_FCNTL_COMMIT
9740: 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 _PHASETWO] opcod
9750: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 e is generated i
9760: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c nternally by SQL
9770: 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 ite.** and sent
9780: 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72 to the VFS after
9790: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 a transaction h
97a0: 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 as been committe
97b0: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a d immediately.**
97c0: 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 but before the
97d0: 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f database is unlo
97e0: 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 cked. VFSes that
97f0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 do not need thi
9800: 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 s signal.** shou
9810: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f ld silently igno
9820: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 re this opcode.
9830: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f Applications sho
9840: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 uld not call.**
9850: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
9860: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 ntrol()] with th
9870: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 is opcode as doi
9880: 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 ng so may disrup
9890: 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 t the .** operat
98a0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 ion of the speci
98b0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 alized VFSes tha
98c0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e t do require it.
98d0: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 .**.** <li>[[S
98e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
98f0: 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 2_AV_RETRY]].**
9900: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
9910: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 TL_WIN32_AV_RETR
9920: 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 Y] opcode is use
9930: 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 d to configure a
9940: 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 utomatic.** retr
9950: 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 y counts and int
9960: 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 ervals for certa
9970: 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 in disk I/O oper
9980: 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a ations for the.*
9990: 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 * windows [VFS]
99a0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 in order to prov
99b0: 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 ide robustness i
99c0: 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f n the presence o
99d0: 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 f.** anti-virus
99e0: 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 programs. By de
99f0: 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f fault, the windo
9a00: 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 ws VFS will retr
9a10: 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 y file read,.**
9a20: 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 file write, and
9a30: 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 file delete oper
9a40: 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 ations up to 10
9a50: 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 times, with a de
9a60: 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c lay.** of 25 mil
9a70: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 liseconds before
9a80: 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 the first retry
9a90: 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 and with the de
9aa0: 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a lay increasing.*
9ab0: 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e * by an addition
9ac0: 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e al 25 millisecon
9ad0: 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 ds with each sub
9ae0: 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 sequent retry.
9af0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 This.** opcode a
9b00: 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 llows these two
9b10: 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 values (10 retri
9b20: 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 es and 25 millis
9b30: 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 econds of delay)
9b40: 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 .** to be adjust
9b50: 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 ed. The values
9b60: 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 are changed for
9b70: 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e all database con
9b80: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 nections.** with
9b90: 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 in the same proc
9ba0: 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ess. The argume
9bb0: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 nt is a pointer
9bc0: 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 to an array of t
9bd0: 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 wo.** integers w
9be0: 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 here the first i
9bf0: 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 nteger i the new
9c00: 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 retry count and
9c10: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 the second.** i
9c20: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 nteger is the de
9c30: 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 lay. If either
9c40: 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 integer is negat
9c50: 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 ive, then the se
9c60: 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 tting.** is not
9c70: 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 changed but inst
9c80: 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 ead the prior va
9c90: 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 lue of that sett
9ca0: 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a ing is written.*
9cb0: 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 * into the array
9cc0: 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 entry, allowing
9cd0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 the current ret
9ce0: 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 ry settings to b
9cf0: 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 e.** interrogate
9d00: 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 d. The zDbName
9d10: 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e parameter is ign
9d20: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ored..**.** <li>
9d30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [[SQLITE_FCNTL_P
9d40: 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 ERSIST_WAL]].**
9d50: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
9d60: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 TL_PERSIST_WAL]
9d70: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
9d80: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 o set or query t
9d90: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 he.** persistent
9da0: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 [WAL | Write Ah
9db0: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 ead Log] setting
9dc0: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 . By default, t
9dd0: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 he auxiliary.**
9de0: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 write ahead log
9df0: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 and shared memor
9e00: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 y files used for
9e10: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e transaction con
9e20: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f trol.** are auto
9e30: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 matically delete
9e40: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 d when the lates
9e50: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 t connection to
9e60: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
9e70: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 closes. Setting
9e80: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 persistent WAL
9e90: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 mode causes thos
9ea0: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 e files to persi
9eb0: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 st after.** clos
9ec0: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 e. Persisting t
9ed0: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 he files is usef
9ee0: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 ul when other pr
9ef0: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 ocesses that do
9f00: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 not.** have writ
9f10: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 e permission on
9f20: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f the directory co
9f30: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 ntaining the dat
9f40: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a abase file want.
9f50: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 ** to read the d
9f60: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 atabase file, as
9f70: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 the WAL and sha
9f80: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 red memory files
9f90: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 must exist.** i
9fa0: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 n order for the
9fb0: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 database to be r
9fc0: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f eadable. The fo
9fd0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
9fe0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 o.** [sqlite3_fi
9ff0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f le_control()] fo
a000: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 r this opcode sh
a010: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 ould be a pointe
a020: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e r to an integer.
a030: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 .** That integer
a040: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 is 0 to disable
a050: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 persistent WAL
a060: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 mode or 1 to ena
a070: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a ble persistent.*
a080: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 * WAL mode. If
a090: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d the integer is -
a0a0: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 1, then it is ov
a0b0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 erwritten with t
a0c0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 he current.** WA
a0d0: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 L persistence se
a0e0: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 tting..**.** <li
a0f0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
a100: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
a110: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 ITE]].** ^The [S
a120: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 QLITE_FCNTL_POWE
a130: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d RSAFE_OVERWRITE]
a140: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
a150: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 to set or query
a160: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e the.** persisten
a170: 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 t "powersafe-ove
a180: 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 rwrite" or "PSOW
a190: 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 " setting. The
a1a0: 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 PSOW setting.**
a1b0: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b determines the [
a1c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 SQLITE_IOCAP_POW
a1d0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
a1e0: 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 ] bit of the.**
a1f0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
a200: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 istics methods.
a210: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
a220: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 eter to.** [sqli
a230: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
a240: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 ()] for this opc
a250: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 ode should be a
a260: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
a270: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 teger..** That i
a280: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 nteger is 0 to d
a290: 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 isable zero-dama
a2a0: 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 ge mode or 1 to
a2b0: 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 enable zero-dama
a2c0: 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 ge.** mode. If
a2d0: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d the integer is -
a2e0: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 1, then it is ov
a2f0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 erwritten with t
a300: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 he current.** ze
a310: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 ro-damage mode s
a320: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c etting..**.** <l
a330: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
a340: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 _OVERWRITE]].**
a350: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
a360: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 TL_OVERWRITE] op
a370: 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 code is invoked
a380: 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 by SQLite after
a390: 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 opening.** a wri
a3a0: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 te transaction t
a3b0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c o indicate that,
a3c0: 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f unless it is ro
a3d0: 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f lled back for so
a3e0: 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 me.** reason, th
a3f0: 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 e entire databas
a400: 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f e file will be o
a410: 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 verwritten by th
a420: 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 e current .** tr
a430: 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 ansaction. This
a440: 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 is used by VACUU
a450: 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a M operations..**
a460: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
a470: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d _FCNTL_VFSNAME]]
a480: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
a490: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 _FCNTL_VFSNAME]
a4a0: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 opcode can be us
a4b0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 ed to obtain the
a4c0: 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c names of.** all
a4d0: 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 [VFSes] in the
a4e0: 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 VFS stack. The
a4f0: 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c names are of all
a500: 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 VFS shims and t
a510: 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 he.** final bott
a520: 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 om-level VFS are
a530: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 written into me
a540: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
a550: 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f om .** [sqlite3_
a560: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 malloc()] and th
a570: 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 e result is stor
a580: 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 ed in the char*
a590: 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 variable.** that
a5a0: 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
a5b0: 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 meter of [sqlite
a5c0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
a5d0: 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 ] points to..**
a5e0: 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 The caller is re
a5f0: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 sponsible for fr
a600: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 eeing the memory
a610: 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 when done. As
a620: 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 with.** all file
a630: 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 -control actions
a640: 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 , there is no gu
a650: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 arantee that thi
a660: 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a s will actually.
a670: 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 ** do anything.
a680: 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 Callers should
a690: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 initialize the c
a6a0: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f har* variable to
a6b0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 a NULL.** point
a6c0: 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 er in case this
a6d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 file-control is
a6e0: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e not implemented.
a6f0: 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 This file-cont
a700: 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 rol.** is intend
a710: 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 ed for diagnosti
a720: 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a c use only..**.*
a730: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
a740: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a CNTL_PRAGMA]].**
a750: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 ^Whenever a [PR
a760: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 AGMA] statement
a770: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 is parsed, an [S
a780: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
a790: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e MA] .** file con
a7a0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 trol is sent to
a7b0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 the open [sqlite
a7c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 3_file] object c
a7d0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 orresponding.**
a7e0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 to the database
a7f0: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 file to which th
a800: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 e pragma stateme
a810: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 nt refers. ^The
a820: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 argument.** to t
a830: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
a840: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
a850: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 ntrol is an arra
a860: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 y of.** pointers
a870: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 to strings (cha
a880: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 r**) in which th
a890: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 e second element
a8a0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a of the array.**
a8b0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
a8c0: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 the pragma and t
a8d0: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 he third element
a8e0: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 is the argument
a8f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d to the.** pragm
a900: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 a or NULL if the
a910: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 pragma has no a
a920: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 rgument. ^The h
a930: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a andler for an.**
a940: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
a950: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 RAGMA] file cont
a960: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c rol can optional
a970: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 ly make the firs
a980: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 t element.** of
a990: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d the char** argum
a9a0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 ent point to a s
a9b0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 tring obtained f
a9c0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 rom [sqlite3_mpr
a9d0: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 intf()].** or th
a9e0: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 e equivalent and
a9f0: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c that string wil
aa00: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 l become the res
aa10: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d ult of the pragm
aa20: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f a or.** the erro
aa30: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 r message if the
aa40: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e pragma fails. ^
aa50: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 If the.** [SQLIT
aa60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
aa70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 file control ret
aa80: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 urns [SQLITE_NOT
aa90: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 FOUND], then nor
aaa0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d mal .** [PRAGMA]
aab0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 processing cont
aac0: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 inues. ^If the
aad0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
aae0: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f AGMA].** file co
aaf0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 ntrol returns [S
ab00: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 QLITE_OK], then
ab10: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d the parser assum
ab20: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 es that the.** V
ab30: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 FS has handled t
ab40: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 he PRAGMA itself
ab50: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 and the parser
ab60: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f generates a no-o
ab70: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 p.** prepared st
ab80: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c atement if resul
ab90: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c t string is NULL
aba0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e , or that return
abb0: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 s a copy.** of t
abc0: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 he result string
abd0: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 if the string i
abe0: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e s non-NULL..** ^
abf0: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 If the [SQLITE_F
ac00: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
ac10: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e e control return
ac20: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 s.** any result
ac30: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 code other than
ac40: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b [SQLITE_OK] or [
ac50: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d SQLITE_NOTFOUND]
ac60: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 , that means.**
ac70: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 that the VFS enc
ac80: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f ountered an erro
ac90: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 r while handling
aca0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e the [PRAGMA] an
acb0: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 d the.** compila
acc0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 tion of the PRAG
acd0: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e MA fails with an
ace0: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 error. ^The [S
acf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
ad00: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 MA].** file cont
ad10: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 rol occurs at th
ad20: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 e beginning of p
ad30: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 ragma statement
ad40: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a analysis and so.
ad50: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f ** it is able to
ad60: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d override built-
ad70: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 in [PRAGMA] stat
ad80: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ements..**.** <l
ad90: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
ada0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a _BUSYHANDLER]].*
adb0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
adc0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 CNTL_BUSYHANDLER
add0: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f ].** file-contro
ade0: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 l may be invoked
adf0: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 by SQLite on th
ae00: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
ae10: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c handle.** shortl
ae20: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 y after it is op
ae30: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f ened in order to
ae40: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f provide a custo
ae50: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 m VFS with acces
ae60: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e s.** to the conn
ae70: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e ections busy-han
ae80: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 dler callback. T
ae90: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f he argument is o
aea0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 f type (void **)
aeb0: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f .** - an array o
aec0: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 f two (void *) v
aed0: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 alues. The first
aee0: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c (void *) actual
aef0: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 ly points.** to
af00: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 a function of ty
af10: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 pe (int (*)(void
af20: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 *)). In order t
af30: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e o invoke the con
af40: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 nections.** busy
af50: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 -handler, this f
af60: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 unction should b
af70: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 e invoked with t
af80: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 he second (void
af90: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 *) in.** the arr
afa0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 ay as the only a
afb0: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 rgument. If it r
afc0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
afd0: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 then the operat
afe0: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 ion.** should be
aff0: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 retried. If it
b000: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 returns zero, th
b010: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f e custom VFS sho
b020: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a uld abandon the.
b030: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 ** current opera
b040: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e tion..**.** <li>
b050: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 [[SQLITE_FCNTL_T
b060: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a EMPFILENAME]].**
b070: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 ^Application ca
b080: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 n invoke the [SQ
b090: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 LITE_FCNTL_TEMPF
b0a0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f ILENAME] file-co
b0b0: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 ntrol.** to have
b0c0: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 SQLite generate
b0d0: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 a.** temporary
b0e0: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 filename using t
b0f0: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 he same algorith
b100: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 m that is follow
b110: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a ed to generate.*
b120: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 * temporary file
b130: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 names for TEMP t
b140: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 ables and other
b150: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 internal uses.
b160: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 The.** argument
b170: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 should be a char
b180: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 ** which will be
b190: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
b1a0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 filename.** wri
b1b0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 tten into memory
b1c0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
b1d0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
b1e0: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 ]. The caller s
b1f0: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 hould.** invoke
b200: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
b210: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 on the result t
b220: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 o avoid a memory
b230: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 leak..**.** <li
b240: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
b250: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 MMAP_SIZE]].** T
b260: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
b270: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 _MMAP_SIZE] file
b280: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 control is used
b290: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 to query or set
b2a0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 the.** maximum
b2b0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
b2c0: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 that will be use
b2d0: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 d for memory-map
b2e0: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 ped I/O..** The
b2f0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
b300: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 inter to a value
b310: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 of type sqlite3
b320: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 _int64 that.** i
b330: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 s an advisory ma
b340: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
b350: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c bytes in the fil
b360: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e e to memory map.
b370: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 The.** pointer
b380: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 is overwritten
b390: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c with the old val
b3a0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 ue. The limit i
b3b0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 s not changed if
b3c0: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 .** the value or
b3d0: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 iginally pointed
b3e0: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c to is negative,
b3f0: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 and so the curr
b400: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 ent limit .** ca
b410: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 n be queried by
b420: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 passing in a poi
b430: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 nter to a negati
b440: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 ve number. This
b450: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c .** file-control
b460: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 is used interna
b470: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 lly to implement
b480: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 [PRAGMA mmap_si
b490: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ze]..**.** <li>[
b4a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 [SQLITE_FCNTL_TR
b4b0: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 ACE]].** The [SQ
b4c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 LITE_FCNTL_TRACE
b4d0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 ] file control p
b4e0: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 rovides advisory
b4f0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
b500: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 to the VFS about
b510: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 what the higher
b520: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 layers of the S
b530: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 QLite stack are
b540: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 doing..** This f
b550: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 ile control is u
b560: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 sed by some VFS
b570: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 activity tracing
b580: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 [shims]..** The
b590: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a argument is a z
b5a0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
b5b0: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c tring. Higher l
b5c0: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 ayers in the.**
b5d0: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 SQLite stack may
b5e0: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e generate instan
b5f0: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 ces of this file
b600: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 control if.** t
b610: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 he [SQLITE_USE_F
b620: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 CNTL_TRACE] comp
b630: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
b640: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a is enabled..**.*
b650: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
b660: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d CNTL_HAS_MOVED]]
b670: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
b680: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d FCNTL_HAS_MOVED]
b690: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e file control in
b6a0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 terprets its arg
b6b0: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f ument as a.** po
b6c0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
b6d0: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 ger and it write
b6e0: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f s a boolean into
b6f0: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 that integer de
b700: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 pending.** on wh
b710: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
b720: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 file has been r
b730: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f enamed, moved, o
b740: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 r deleted since
b750: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 it.** was first
b760: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c opened..**.** <l
b770: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
b780: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c _WIN32_SET_HANDL
b790: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 E]].** The [SQLI
b7a0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 TE_FCNTL_WIN32_S
b7b0: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 ET_HANDLE] opcod
b7c0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 e is used for de
b7d0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a bugging. This.*
b7e0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 * opcode causes
b7f0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
b800: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 method to swap
b810: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 the file handle
b820: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 with the one.**
b830: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 pointed to by th
b840: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e e pArg argument.
b850: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 This capabilit
b860: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 y is used during
b870: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 testing.** and
b880: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 only needs to be
b890: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 supported when
b8a0: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 SQLITE_TEST is d
b8b0: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c efined..**.** <l
b8c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
b8d0: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 _WAL_BLOCK]].**
b8e0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
b8f0: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 L_WAL_BLOCK] is
b900: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 a signal to the
b910: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69 VFS layer that i
b920: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 t might.** be ad
b930: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c vantageous to bl
b940: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 ock on the next
b950: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 WAL lock if the
b960: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 lock is not imme
b970: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c diately.** avail
b980: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73 able. The WAL s
b990: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20 ubsystem issues
b9a0: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69 this signal duri
b9b0: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 ng rare.** circu
b9c0: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 mstances in orde
b9d0: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c r to fix a probl
b9e0: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79 em with priority
b9f0: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 inversion..** A
ba00: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
ba10: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 ld <em>not</em>
ba20: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f use this file-co
ba30: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ntrol..**.** <li
ba40: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
ba50: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 ZIPVFS]].** The
ba60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 [SQLITE_FCNTL_ZI
ba70: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 PVFS] opcode is
ba80: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a implemented by z
ba90: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 ipvfs only. All
baa0: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f other.** VFS sho
bab0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 uld return SQLIT
bac0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 E_NOTFOUND for t
bad0: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a his opcode..**.*
bae0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
baf0: 43 4e 54 4c 5f 4f 54 41 5d 5d 0a 2a 2a 20 54 68 CNTL_OTA]].** Th
bb00: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
bb10: 4f 54 41 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 OTA] opcode is i
bb20: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68 mplemented by th
bb30: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73 e special VFS us
bb40: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 4f 54 41 ed by.** the OTA
bb50: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e extension only.
bb60: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 All other VFS
bb70: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 should return SQ
bb80: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f LITE_NOTFOUND fo
bb90: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 r.** this opcode
bba0: 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a . .** </ul>.*/.
bbb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
bbc0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 CNTL_LOCKSTATE
bbd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 1.#
bbe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
bbf0: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 NTL_GET_LOCKPROX
bc00: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 YFILE 2.#d
bc10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
bc20: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TL_SET_LOCKPROXY
bc30: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 FILE 3.#de
bc40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
bc50: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 L_LAST_ERRNO
bc60: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
bc70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
bc80: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 _SIZE_HINT
bc90: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 5.#defi
bca0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
bcb0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 CHUNK_SIZE
bcc0: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 6.#defin
bcd0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 e SQLITE_FCNTL_F
bce0: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 ILE_POINTER
bcf0: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 7.#define
bd00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 SQLITE_FCNTL_SY
bd10: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 NC_OMITTED
bd20: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 8.#define
bd30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
bd40: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 32_AV_RETRY
bd50: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 9.#define S
bd60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 QLITE_FCNTL_PERS
bd70: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 IST_WAL
bd80: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 10.#define SQ
bd90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 LITE_FCNTL_OVERW
bda0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 RITE
bdb0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 11.#define SQL
bdc0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d ITE_FCNTL_VFSNAM
bdd0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
bde0: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 12.#define SQLI
bdf0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 TE_FCNTL_POWERSA
be00: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 FE_OVERWRITE
be10: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 13.#define SQLIT
be20: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 E_FCNTL_PRAGMA
be30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
be40: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
be50: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c _FCNTL_BUSYHANDL
be60: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 ER 15
be70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
be80: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 FCNTL_TEMPFILENA
be90: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a ME 16.
bea0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
beb0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 CNTL_MMAP_SIZE
bec0: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 18.#
bed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
bee0: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 NTL_TRACE
bef0: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 19.#d
bf00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
bf10: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 TL_HAS_MOVED
bf20: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 20.#de
bf30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
bf40: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 L_SYNC
bf50: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 21.#def
bf60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
bf70: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f _COMMIT_PHASETWO
bf80: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 22.#defi
bf90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
bfa0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 WIN32_SET_HANDLE
bfb0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 23.#defin
bfc0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 e SQLITE_FCNTL_W
bfd0: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 AL_BLOCK
bfe0: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 24.#define
bff0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 SQLITE_FCNTL_ZI
c000: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 PVFS
c010: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 25.#define
c020: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 54 41 SQLITE_FCNTL_OTA
c030: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
c040: 20 20 20 20 32 36 0a 0a 2f 2a 20 64 65 70 72 65 26../* depre
c050: 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 cated names */.#
c060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 define SQLITE_GE
c070: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
c080: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 SQLITE_FCNT
c090: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 L_GET_LOCKPROXYF
c0a0: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 ILE.#define SQLI
c0b0: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TE_SET_LOCKPROXY
c0c0: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 FILE SQLITE
c0d0: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 _FCNTL_SET_LOCKP
c0e0: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 ROXYFILE.#define
c0f0: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 SQLITE_LAST_ERR
c100: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 NO S
c110: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 QLITE_FCNTL_LAST
c120: 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 _ERRNO.../*.** C
c130: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 API3REF: Mutex H
c140: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 andle.**.** The
c150: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 mutex module wit
c160: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e hin SQLite defin
c170: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 es [sqlite3_mute
c180: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 x] to be an.** a
c190: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 bstract type for
c1a0: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e a mutex object.
c1b0: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 The SQLite cor
c1c0: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a e never looks.**
c1d0: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c at the internal
c1e0: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
c1f0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d of an [sqlite3_m
c200: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a utex]. It only.
c210: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f ** deals with po
c220: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 inters to the [s
c230: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 qlite3_mutex] ob
c240: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 ject..**.** Mute
c250: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 xes are created
c260: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
c270: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a utex_alloc()]..*
c280: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
c290: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 sqlite3_mutex s
c2a0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f qlite3_mutex;../
c2b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
c2c0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 S Interface Obje
c2d0: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 ct.**.** An inst
c2e0: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 ance of the sqli
c2f0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 te3_vfs object d
c300: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
c310: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 face between.**
c320: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 the SQLite core
c330: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 and the underlyi
c340: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ng operating sys
c350: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a tem. The "vfs".
c360: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f ** in the name o
c370: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 f the object sta
c380: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c nds for "virtual
c390: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 file system".
c3a0: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 See.** the [VFS
c3b0: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 | VFS documentat
c3c0: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 ion] for further
c3d0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
c3e0: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 .** The value of
c3f0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 the iVersion fi
c400: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 eld is initially
c410: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 1 but may be la
c420: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 rger in.** futur
c430: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
c440: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 Lite. Additiona
c450: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 l fields may be
c460: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 appended to this
c470: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 .** object when
c480: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c the iVersion val
c490: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e ue is increased.
c4a0: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 Note that the
c4b0: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 structure.** of
c4c0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
c4d0: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 object changes i
c4e0: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f n the transactio
c4f0: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c n between.** SQL
c500: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
c510: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 9 and 3.6.0 and
c520: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e yet the iVersion
c530: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a field was not.*
c540: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a * modified..**.*
c550: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 * The szOsFile f
c560: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 ield is the size
c570: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 of the subclass
c580: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ed [sqlite3_file
c590: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 ].** structure u
c5a0: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e sed by this VFS.
c5b0: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 mxPathname is
c5c0: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 the maximum leng
c5d0: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e th of.** a pathn
c5e0: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e ame in this VFS.
c5f0: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 .**.** Registere
c600: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 d sqlite3_vfs ob
c610: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f jects are kept o
c620: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 n a linked list
c630: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 formed by.** the
c640: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 pNext pointer.
c650: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 The [sqlite3_vf
c660: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a s_register()].**
c670: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 and [sqlite3_vf
c680: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 s_unregister()]
c690: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 interfaces manag
c6a0: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 e this list.** i
c6b0: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 n a thread-safe
c6c0: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 way. The [sqlit
c6d0: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 e3_vfs_find()] i
c6e0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 nterface.** sear
c6f0: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 ches the list.
c700: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c Neither the appl
c710: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 ication code nor
c720: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c the VFS.** impl
c730: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c ementation shoul
c740: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 d use the pNext
c750: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 pointer..**.** T
c760: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 he pNext field i
c770: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 s the only field
c780: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f in the sqlite3_
c790: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 vfs.** structure
c7a0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
c7b0: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 l ever modify.
c7c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 SQLite will only
c7d0: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f access.** or mo
c7e0: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 dify this field
c7f0: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 while holding a
c800: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 particular stati
c810: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 c mutex..** The
c820: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
c830: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 ld never modify
c840: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 anything within
c850: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a the sqlite3_vfs.
c860: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 ** object once t
c870: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 he object has be
c880: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a en registered..*
c890: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 *.** The zName f
c8a0: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e ield holds the n
c8b0: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d ame of the VFS m
c8c0: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 odule. The name
c8d0: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 must.** be uniq
c8e0: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 ue across all VF
c8f0: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a S modules..**.**
c900: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 [[sqlite3_vfs.x
c910: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 Open]].** ^SQLit
c920: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 e guarantees tha
c930: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 t the zFilename
c940: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
c950: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 en.** is either
c960: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f a NULL pointer o
c970: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 r string obtaine
c980: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 d.** from xFullP
c990: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 athname() with a
c9a0: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 n optional suffi
c9b0: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 x added..** ^If
c9c0: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 a suffix is adde
c9d0: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 d to the zFilena
c9e0: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 me parameter, it
c9f0: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 will.** consist
ca00: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 of a single "-"
ca10: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f character follo
ca20: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 wed by no more t
ca30: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e han.** 11 alphan
ca40: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d umeric and/or "-
ca50: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a " characters..**
ca60: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 ^SQLite further
ca70: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
ca80: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 .** the string w
ca90: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 ill be valid and
caa0: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c unchanged until
cab0: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 xClose() is.**
cac0: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 called. Because
cad0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 of the previous
cae0: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 sentence,.** the
caf0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
cb00: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 can safely store
cb10: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
cb20: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 e.** filename if
cb30: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d it needs to rem
cb40: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 ember the filena
cb50: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 me for some reas
cb60: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 on..** If the zF
cb70: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
cb80: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 r to xOpen is a
cb90: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
cba0: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 n xOpen.** must
cbb0: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 invent its own t
cbc0: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f emporary name fo
cbd0: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 r the file. ^Wh
cbe0: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 enever the .** x
cbf0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
cc00: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 er is NULL it wi
cc10: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 ll also be the c
cc20: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ase that the.**
cc30: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
cc40: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 will include [SQ
cc50: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
cc60: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 ONCLOSE]..**.**
cc70: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
cc80: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e nt to xOpen() in
cc90: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 cludes all bits
cca0: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c set in.** the fl
ccb0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ags argument to
ccc0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
ccd0: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c ()]. Or if [sql
cce0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 ite3_open()].**
ccf0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e or [sqlite3_open
cd00: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 16()] is used, t
cd10: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 hen flags includ
cd20: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b es at least.** [
cd30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
cd40: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 WRITE] | [SQLITE
cd50: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a _OPEN_CREATE]. .
cd60: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 ** If xOpen() op
cd70: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d ens a file read-
cd80: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 only then it set
cd90: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a s *pOutFlags to.
cda0: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 ** include [SQLI
cdb0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
cdc0: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 ]. Other bits i
cdd0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 n *pOutFlags may
cde0: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e be set..**.** ^
cdf0: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 (SQLite will als
ce00: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 o add one of the
ce10: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 following flags
ce20: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a to the xOpen().
ce30: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 ** call, dependi
ce40: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 ng on the object
ce50: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a being opened:.*
ce60: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
ce70: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
ce80: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e MAIN_DB].** <li>
ce90: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
cea0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 AIN_JOURNAL].**
ceb0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
cec0: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c EN_TEMP_DB].** <
ced0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
cee0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a N_TEMP_JOURNAL].
cef0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
cf00: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f _OPEN_TRANSIENT_
cf10: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
cf20: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 LITE_OPEN_SUBJOU
cf30: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
cf40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 SQLITE_OPEN_MAST
cf50: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c ER_JOURNAL].** <
cf60: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
cf70: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 N_WAL].** </ul>)
cf80: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 ^.**.** The file
cf90: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 I/O implementat
cfa0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 ion can use the
cfb0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 object type flag
cfc0: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 s to.** change t
cfd0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 he way it deals
cfe0: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 with files. For
cff0: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 example, an app
d000: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 lication.** that
d010: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 does not care a
d020: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 bout crash recov
d030: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 ery or rollback
d040: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 might make.** th
d050: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 e open of a jour
d060: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 nal file a no-op
d070: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 . Writes to thi
d080: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a s journal would.
d090: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 ** also be no-op
d0a0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d s, and any attem
d0b0: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a pt to read the j
d0c0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 ournal would ret
d0d0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f urn.** SQLITE_IO
d0e0: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 ERR. Or the imp
d0f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 lementation migh
d100: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 t recognize that
d110: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 a database.** f
d120: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e ile will be doin
d130: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 g page-aligned s
d140: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 ector reads and
d150: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 writes in a rand
d160: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 om.** order and
d170: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 set up its I/O s
d180: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 ubsystem accordi
d190: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 ngly..**.** SQLi
d1a0: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 te might also ad
d1b0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c d one of the fol
d1c0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 lowing flags to
d1d0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 the xOpen method
d1e0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
d1f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 <li> [SQLITE_OPE
d200: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
d210: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
d220: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d _OPEN_EXCLUSIVE]
d230: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
d240: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
d250: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 _DELETEONCLOSE]
d260: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 flag means the f
d270: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a ile should be.**
d280: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 deleted when it
d290: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 is closed. ^Th
d2a0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 e [SQLITE_OPEN_D
d2b0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a ELETEONCLOSE].**
d2c0: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 will be set for
d2d0: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 TEMP databases
d2e0: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 and their journa
d2f0: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a ls, transient.**
d300: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 databases, and
d310: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a subjournals..**.
d320: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
d330: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 OPEN_EXCLUSIVE]
d340: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 flag is always u
d350: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 sed in conjuncti
d360: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b on.** with the [
d370: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
d380: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 TE] flag, which
d390: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c are both directl
d3a0: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 y.** analogous t
d3b0: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 o the O_EXCL and
d3c0: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f O_CREAT flags o
d3d0: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e f the POSIX open
d3e0: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 ().** API. The
d3f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
d400: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e USIVE flag, when
d410: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 paired with the
d420: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e .** SQLITE_OPEN
d430: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 _CREATE, is used
d440: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
d450: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c t file should al
d460: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 ways.** be creat
d470: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 ed, and that it
d480: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 is an error if i
d490: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 t already exists
d4a0: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f ..** It is <i>no
d4b0: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e t</i> used to in
d4c0: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 dicate the file
d4d0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 should be opened
d4e0: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 .** for exclusi
d4f0: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a ve access..**.**
d500: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 ^At least szOsF
d510: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d ile bytes of mem
d520: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 ory are allocate
d530: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 d by SQLite.** t
d540: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c o hold the [sql
d550: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 ite3_file] struc
d560: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 ture passed as t
d570: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 he third.** argu
d580: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 ment to xOpen.
d590: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 The xOpen method
d5a0: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 does not have t
d5b0: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 o.** allocate th
d5c0: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 e structure; it
d5d0: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c should just fill
d5e0: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 it in. Note th
d5f0: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 at.** the xOpen
d600: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 method must set
d610: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 the sqlite3_file
d620: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 .pMethods to eit
d630: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b her.** a valid [
d640: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
d650: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f ds] object or to
d660: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 NULL. xOpen mu
d670: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 st do.** this ev
d680: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 en if the open f
d690: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 ails. SQLite ex
d6a0: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 pects that the s
d6b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 qlite3_file.pMet
d6c0: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 hods.** element
d6d0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 will be valid af
d6e0: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e ter xOpen return
d6f0: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 s regardless of
d700: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f the success.** o
d710: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 r failure of the
d720: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a xOpen call..**.
d730: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 ** [[sqlite3_vfs
d740: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 .xAccess]].** ^T
d750: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
d760: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d t to xAccess() m
d770: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 ay be [SQLITE_AC
d780: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 CESS_EXISTS].**
d790: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 to test for the
d7a0: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 existence of a f
d7b0: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f ile, or [SQLITE_
d7c0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
d7d0: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 ] to.** test whe
d7e0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 ther a file is r
d7f0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 eadable and writ
d800: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 able, or [SQLITE
d810: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a _ACCESS_READ].**
d820: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 to test whether
d830: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 a file is at le
d840: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 ast readable.
d850: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 The file can be
d860: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a a.** directory..
d870: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 **.** ^SQLite wi
d880: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 ll always alloca
d890: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 te at least mxPa
d8a0: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 thname+1 bytes f
d8b0: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 or the.** output
d8c0: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 buffer xFullPat
d8d0: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 hname. The exac
d8e0: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 t size of the ou
d8f0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
d900: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 s also passed as
d910: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 a parameter to
d920: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 both methods. I
d930: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
d940: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 fer.** is not la
d950: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c rge enough, [SQL
d960: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 ITE_CANTOPEN] sh
d970: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
d980: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a . Since this is.
d990: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 ** handled as a
d9a0: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 fatal error by S
d9b0: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 QLite, vfs imple
d9c0: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c mentations shoul
d9d0: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f d endeavor.** to
d9e0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 prevent this by
d9f0: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e setting mxPathn
da00: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 ame to a suffici
da10: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 ently large valu
da20: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 e..**.** The xRa
da30: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 ndomness(), xSle
da40: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 ep(), xCurrentTi
da50: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 me(), and xCurre
da60: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a ntTimeInt64().**
da70: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
da80: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 not strictly a p
da90: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 art of the files
daa0: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 ystem, but they
dab0: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 are.** included
dac0: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 in the VFS struc
dad0: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 ture for complet
dae0: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 eness..** The xR
daf0: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 andomness() func
db00: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f tion attempts to
db10: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 return nBytes b
db20: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d ytes.** of good-
db30: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 quality randomne
db40: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 ss into zOut. T
db50: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
db60: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c is.** the actual
db70: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
db80: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f of randomness o
db90: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 btained..** The
dba0: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 xSleep() method
dbb0: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 causes the calli
dbc0: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 ng thread to sle
dbd0: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 ep for at.** lea
dbe0: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 st the number of
dbf0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 microseconds gi
dc00: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 ven. ^The xCurr
dc10: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 entTime().** met
dc20: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 hod returns a Ju
dc30: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 lian Day Number
dc40: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 for the current
dc50: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 date and time as
dc60: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 .** a floating p
dc70: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e oint value..** ^
dc80: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 The xCurrentTime
dc90: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 Int64() method r
dca0: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e eturns, as an in
dcb0: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 teger, the Julia
dcc0: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 n.** Day Number
dcd0: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 multiplied by 86
dce0: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 400000 (the numb
dcf0: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
dd00: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 ds in .** a 24-h
dd10: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e our day). .** ^
dd20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 SQLite will use
dd30: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 the xCurrentTime
dd40: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 Int64() method t
dd50: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e o get the curren
dd60: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 t.** date and ti
dd70: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f me if that metho
dd80: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 d is available (
dd90: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 if iVersion is 2
dda0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 or .** greater
ddb0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e and the function
ddc0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
ddd0: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 NULL) and will f
dde0: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 all back.** to x
ddf0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 CurrentTime() if
de00: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 xCurrentTimeInt
de10: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 64() is unavaila
de20: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ble..**.** ^The
de30: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 xSetSystemCall()
de40: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c , xGetSystemCall
de50: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 (), and xNestSys
de60: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 temCall() interf
de70: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 aces.** are not
de80: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 used by the SQLi
de90: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 te core. These
dea0: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 optional interfa
deb0: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 ces are provided
dec0: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 .** by some VFSe
ded0: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 s to facilitate
dee0: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 testing of the V
def0: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 FS code. By over
df00: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 riding .** syste
df10: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e m calls with fun
df20: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 ctions under its
df30: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 control, a test
df40: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 program can.**
df50: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 simulate faults
df60: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 and error condit
df70: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 ions that would
df80: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 otherwise be dif
df90: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 ficult.** or imp
dfa0: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 ossible to induc
dfb0: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 e. The set of s
dfc0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 ystem calls that
dfd0: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 can be overridd
dfe0: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f en.** varies fro
dff0: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f m one VFS to ano
e000: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f ther, and from o
e010: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 ne version of th
e020: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 e same VFS to th
e030: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c e.** next. Appl
e040: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 ications that us
e050: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 e these interfac
e060: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 es must be prepa
e070: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f red for any.** o
e080: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 r all of these i
e090: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 nterfaces to be
e0a0: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 NULL or for thei
e0b0: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 r behavior to ch
e0c0: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 ange.** from one
e0d0: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 release to the
e0e0: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 next. Applicati
e0f0: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 ons must not att
e100: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a empt to access.*
e110: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d * any of these m
e120: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 ethods if the iV
e130: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 ersion of the VF
e140: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 S is less than 3
e150: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
e160: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 uct sqlite3_vfs
e170: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 sqlite3_vfs;.typ
e180: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 edef void (*sqli
e190: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 te3_syscall_ptr)
e1a0: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 (void);.struct s
e1b0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 qlite3_vfs {. i
e1c0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 nt iVersion;
e1d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 /* Struc
e1e0: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d ture version num
e1f0: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 ber (currently 3
e200: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 ) */. int szOsF
e210: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 ile;
e220: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c /* Size of subcl
e230: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 assed sqlite3_fi
e240: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 le */. int mxPa
e250: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 thname;
e260: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 /* Maximum file
e270: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 pathname length
e280: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 */. sqlite3_vf
e290: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f s *pNext; /
e2a0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 * Next registere
e2b0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 d VFS */. const
e2c0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 char *zName;
e2d0: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
e2e0: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 his virtual file
e2f0: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 system */. voi
e300: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
e310: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 /* Pointer
e320: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d to application-
e330: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f specific data */
e340: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 . int (*xOpen)(
e350: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
e360: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
e370: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a sqlite3_file*,.
e380: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 i
e390: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 nt flags, int *p
e3a0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 OutFlags);. int
e3b0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 (*xDelete)(sqli
e3c0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
e3d0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
e3e0: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 syncDir);. int
e3f0: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 (*xAccess)(sqli
e400: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
e410: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
e420: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 flags, int *pRe
e430: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sOut);. int (*x
e440: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 FullPathname)(sq
e450: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
e460: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 t char *zName, i
e470: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a nt nOut, char *z
e480: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a Out);. void *(*
e490: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 xDlOpen)(sqlite3
e4a0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
e4b0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 r *zFilename);.
e4c0: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 void (*xDlError
e4d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e4e0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 int nByte, char
e4f0: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 *zErrMsg);. voi
e500: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 d (*(*xDlSym)(sq
e510: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a lite3_vfs*,void*
e520: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 , const char *zS
e530: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 ymbol))(void);.
e540: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 void (*xDlClose
e550: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e560: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a void*);. int (*
e570: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c xRandomness)(sql
e580: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e ite3_vfs*, int n
e590: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 Byte, char *zOut
e5a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 );. int (*xSlee
e5b0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c p)(sqlite3_vfs*,
e5c0: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 int microsecond
e5d0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 s);. int (*xCur
e5e0: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 rentTime)(sqlite
e5f0: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3_vfs*, double*)
e600: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 ;. int (*xGetLa
e610: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 stError)(sqlite3
e620: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 _vfs*, int, char
e630: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 *);. /*. ** T
e640: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
e650: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 are in version
e660: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 1 of the sqlite_
e670: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 vfs object. **
e680: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f definition. Tho
e690: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 se that follow a
e6a0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 re added in vers
e6b0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 ion 2 or later.
e6c0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 */. int (*xCur
e6d0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 rentTimeInt64)(s
e6e0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c qlite3_vfs*, sql
e6f0: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 ite3_int64*);.
e700: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
e710: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
e720: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 versions 1 and
e730: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 2 of the sqlite_
e740: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a vfs object.. **
e750: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 Those below are
e760: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 for version 3 a
e770: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f nd greater.. */
e780: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 . int (*xSetSys
e790: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 temCall)(sqlite3
e7a0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
e7b0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 r *zName, sqlite
e7c0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 3_syscall_ptr);.
e7d0: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c sqlite3_syscal
e7e0: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 l_ptr (*xGetSyst
e7f0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f emCall)(sqlite3_
e800: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
e810: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 *zName);. cons
e820: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 t char *(*xNextS
e830: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 ystemCall)(sqlit
e840: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
e850: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f har *zName);. /
e860: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
e870: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
e880: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 versions 1 throu
e890: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 gh 3 of the sqli
e8a0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 te_vfs object..
e8b0: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d ** New fields m
e8c0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 ay be appended i
e8d0: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e n figure version
e8e0: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e s. The iVersion
e8f0: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c . ** value will
e900: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 increment whene
e910: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 ver this happens
e920: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a . . */.};../*.*
e930: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 * CAPI3REF: Flag
e940: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 s for the xAcces
e950: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a s VFS method.**.
e960: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 ** These integer
e970: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 constants can b
e980: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 e used as the th
e990: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
e9a0: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 .** the xAccess
e9b0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 method of an [sq
e9c0: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
e9d0: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 t. They determi
e9e0: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 ne.** what kind
e9f0: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 of permissions t
ea00: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
ea10: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 d is looking for
ea20: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 ..** With SQLITE
ea30: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 _ACCESS_EXISTS,
ea40: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
ea50: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 od.** simply che
ea60: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
ea70: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 file exists..**
ea80: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 With SQLITE_ACCE
ea90: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 SS_READWRITE, th
eaa0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
eab0: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 .** checks wheth
eac0: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 er the named dir
ead0: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 ectory is both r
eae0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 eadable and writ
eaf0: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 able.** (in othe
eb00: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 r words, if file
eb10: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 s can be added,
eb20: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e removed, and ren
eb30: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 amed within.** t
eb40: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a he directory)..*
eb50: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 * The SQLITE_ACC
eb60: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f ESS_READWRITE co
eb70: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e nstant is curren
eb80: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 tly used only by
eb90: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 the.** [temp_st
eba0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
ebb0: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 agma], though th
ebc0: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 is could change
ebd0: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 in a future.** r
ebe0: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
ebf0: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 ..** With SQLITE
ec00: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 _ACCESS_READ, th
ec10: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
ec20: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 .** checks wheth
ec30: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 er the file is r
ec40: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 eadable. The SQ
ec50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
ec60: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 constant is.**
ec70: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 currently unused
ec80: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 , though it migh
ec90: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 t be used in a f
eca0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 uture release of
ecb0: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 .** SQLite..*/.#
ecc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
ecd0: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 CESS_EXISTS 0
ece0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
ecf0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
ed00: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 1 /* Used by
ed10: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 PRAGMA temp_stor
ed20: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 e_directory */.#
ed30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
ed40: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 CESS_READ 2
ed50: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a /* Unused */.
ed60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
ed70: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 Flags for the x
ed80: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 ShmLock VFS meth
ed90: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 od.**.** These i
eda0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
edb0: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 define the vari
edc0: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 ous locking oper
edd0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 ations.** allowe
ede0: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 d by the xShmLoc
edf0: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c k method of [sql
ee00: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
ee10: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 . The.** follow
ee20: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 ing are the only
ee30: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 legal combinati
ee40: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 ons of flags to
ee50: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 the.** xShmLock
ee60: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 method:.**.** <u
ee70: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 l>.** <li> SQLI
ee80: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 TE_SHM_LOCK | SQ
ee90: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a LITE_SHM_SHARED.
eea0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
eeb0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 SHM_LOCK | SQLIT
eec0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a E_SHM_EXCLUSIVE.
eed0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
eee0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c SHM_UNLOCK | SQL
eef0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a ITE_SHM_SHARED.*
ef00: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
ef10: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 HM_UNLOCK | SQLI
ef20: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
ef30: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
ef40: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 When unlocking,
ef50: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 the same SHARED
ef60: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 or EXCLUSIVE fla
ef70: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 g must be suppli
ef80: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 ed as.** was giv
ef90: 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 en on the corres
efa0: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a ponding lock. .
efb0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f **.** The xShmLo
efc0: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 ck method can tr
efd0: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e ansition between
efe0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 unlocked and SH
eff0: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 ARED or.** betwe
f000: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 en unlocked and
f010: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 EXCLUSIVE. It c
f020: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e annot transition
f030: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a between SHARED.
f040: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 ** and EXCLUSIVE
f050: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
f060: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 ITE_SHM_UNLOCK
f070: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
f080: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 QLITE_SHM_LOCK
f090: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
f0a0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 SQLITE_SHM_SHAR
f0b0: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 ED 4.#defi
f0c0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 ne SQLITE_SHM_EX
f0d0: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a CLUSIVE 8../*
f0e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 .** CAPI3REF: Ma
f0f0: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 ximum xShmLock i
f100: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ndex.**.** The x
f110: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f ShmLock method o
f120: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 n [sqlite3_io_me
f130: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 thods] may use v
f140: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e alues.** between
f150: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 0 and this uppe
f160: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 r bound as its "
f170: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 offset" argument
f180: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 ..** The SQLite
f190: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 core will never
f1a0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 attempt to acqui
f1b0: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a re or release a.
f1c0: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 ** lock outside
f1d0: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f of this range.*/
f1e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
f1f0: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 SHM_NLOCK
f200: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 8.../*.** CAPI3
f210: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 REF: Initialize
f220: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 The SQLite Libra
f230: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ry.**.** ^The sq
f240: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f250: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 () routine initi
f260: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 alizes the.** SQ
f270: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e Lite library. ^
f280: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 The sqlite3_shut
f290: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a down() routine.*
f2a0: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e * deallocates an
f2b0: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 y resources that
f2c0: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 were allocated
f2d0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 by sqlite3_initi
f2e0: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 alize()..** Thes
f2f0: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 e routines are d
f300: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 esigned to aid i
f310: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 n process initia
f320: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 lization and.**
f330: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 shutdown on embe
f340: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 dded systems. W
f350: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 orkstation appli
f360: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a cations using.**
f370: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 SQLite normally
f380: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 do not need to
f390: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 invoke either of
f3a0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
f3b0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f .**.** A call to
f3c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
f3d0: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 ize() is an "eff
f3e0: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 ective" call if
f3f0: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 it is.** the fir
f400: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f st time sqlite3_
f410: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
f420: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 invoked during t
f430: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a he lifetime of.*
f440: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f * the process, o
f450: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 r if it is the f
f460: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 irst time sqlite
f470: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
f480: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c s invoked.** fol
f490: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f lowing a call to
f4a0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
f4b0: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 n(). ^(Only an
f4c0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a effective call.*
f4d0: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 * of sqlite3_ini
f4e0: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 tialize() does a
f4f0: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ny initializatio
f500: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 n. All other ca
f510: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c lls.** are harml
f520: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a ess no-ops.)^.**
f530: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 .** A call to sq
f540: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f550: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 is an "effectiv
f560: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 e" call if it is
f570: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 the first.** ca
f580: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
f590: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 utdown() since t
f5a0: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f he last sqlite3_
f5b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e initialize(). ^
f5c0: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 (Only.** an effe
f5d0: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 ctive call to sq
f5e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f5f0: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 does any deinit
f600: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 ialization..** A
f610: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 ll other valid c
f620: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
f630: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 shutdown() are h
f640: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 armless no-ops.)
f650: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ^.**.** The sqli
f660: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
f670: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 interface is th
f680: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 readsafe, but sq
f690: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f6a0: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 .** is not. The
f6b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
f6c0: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 n() interface mu
f6d0: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 st only be calle
f6e0: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 d from a.** sing
f6f0: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 le thread. All
f700: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 open [database c
f710: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 onnections] must
f720: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 be closed and a
f730: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 ll.** other SQLi
f740: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 te resources mus
f750: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 t be deallocated
f760: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 prior to invoki
f770: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 ng.** sqlite3_sh
f780: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 utdown()..**.**
f790: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e Among other thin
f7a0: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 gs, ^sqlite3_ini
f7b0: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 tialize() will i
f7c0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
f7d0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d _os_init(). Sim
f7e0: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 ilarly, ^sqlite3
f7f0: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 _shutdown().** w
f800: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 ill invoke sqlit
f810: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a e3_os_end()..**.
f820: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
f830: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
f840: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 tine returns [SQ
f850: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
f860: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 ess..** ^If for
f870: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c some reason, sql
f880: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
f890: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 ) is unable to i
f8a0: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 nitialize.** the
f8b0: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 library (perhap
f8c0: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 s it is unable t
f8d0: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 o allocate a nee
f8e0: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 ded resource suc
f8f0: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 h.** as a mutex)
f900: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b it returns an [
f910: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 error code] othe
f920: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f r than [SQLITE_O
f930: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 K]..**.** ^The s
f940: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
f950: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 e() routine is c
f960: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 alled internally
f970: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a by many other.*
f980: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 * SQLite interfa
f990: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 ces so that an a
f9a0: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c pplication usual
f9b0: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ly does not need
f9c0: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 to.** invoke sq
f9d0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f9e0: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f () directly. Fo
f9f0: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 r example, [sqli
fa00: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 te3_open()].** c
fa10: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 alls sqlite3_ini
fa20: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 tialize() so the
fa30: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 SQLite library
fa40: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 will be automati
fa50: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c cally.** initial
fa60: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 ized when [sqlit
fa70: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 e3_open()] is ca
fa80: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e lled if it has n
fa90: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 ot be initialize
faa0: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e d.** already. ^
fab0: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 However, if SQLi
fac0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
fad0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
fae0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a OMIT_AUTOINIT].*
faf0: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f * compile-time o
fb00: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ption, then the
fb10: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 automatic calls
fb20: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 to sqlite3_initi
fb30: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f alize().** are o
fb40: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 mitted and the a
fb50: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
fb60: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 call sqlite3_ini
fb70: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 tialize() direct
fb80: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 ly.** prior to u
fb90: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 sing any other S
fba0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
fbb0: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f For maximum po
fbc0: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 rtability,.** it
fbd0: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
fbe0: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
fbf0: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 s always invoke
fc00: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
fc10: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 ze().** directly
fc20: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 prior to using
fc30: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 any other SQLite
fc40: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 interface. Fut
fc50: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 ure releases.**
fc60: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 of SQLite may re
fc70: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 quire this. In
fc80: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
fc90: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 behavior exhibi
fca0: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 ted.** when SQLi
fcb0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
fcc0: 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 ith [SQLITE_OMIT
fcd0: 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 _AUTOINIT] might
fce0: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 become the.** d
fcf0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 efault behavior
fd00: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 in some future r
fd10: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
fd20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
fd30: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f te3_os_init() ro
fd40: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 utine does opera
fd50: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 ting-system spec
fd60: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 ific.** initiali
fd70: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 zation of the SQ
fd80: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 Lite library. T
fd90: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e he sqlite3_os_en
fda0: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 d().** routine u
fdb0: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 ndoes the effect
fdc0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 of sqlite3_os_i
fdd0: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 nit(). Typical
fde0: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d tasks.** perform
fdf0: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 ed by these rout
fe00: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c ines include all
fe10: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c ocation or deall
fe20: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 ocation.** of st
fe30: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 atic resources,
fe40: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f initialization o
fe50: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c f global variabl
fe60: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 es,.** setting u
fe70: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c p a default [sql
fe80: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 ite3_vfs] module
fe90: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a , or setting up.
fea0: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e ** a default con
feb0: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 figuration using
fec0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
fed0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 ()]..**.** The a
fee0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
fef0: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 d never invoke e
ff00: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 ither sqlite3_os
ff10: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 _init().** or sq
ff20: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 lite3_os_end() d
ff30: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 irectly. The ap
ff40: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
ff50: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 only invoke.**
ff60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
ff70: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 ze() and sqlite3
ff80: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 _shutdown(). Th
ff90: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 e sqlite3_os_ini
ffa0: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 t().** interface
ffb0: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d is called autom
ffc0: 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 atically by sqli
ffd0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
ffe0: 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f and.** sqlite3_
fff0: 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c os_end() is call
10000 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 ed by sqlite3_sh
10010 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f utdown(). Appro
10020 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d priate.** implem
10030 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 entations for sq
10040 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
10050 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 and sqlite3_os_e
10060 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c nd().** are buil
10070 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 t into SQLite wh
10080 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 en it is compile
10090 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 d for Unix, Wind
100a0 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a ows, or OS/2..**
100b0 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 When [custom bu
100c0 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 ilds | built for
100d0 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 other platforms
100e0 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 ].** (using the
100f0 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 [SQLITE_OS_OTHER
10100 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =1] compile-time
10110 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 .** option) the
10120 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
10130 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 supply a suitab
10140 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
10150 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 n for.** sqlite3
10160 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 _os_init() and s
10170 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e qlite3_os_end().
10180 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e An application
10190 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 -supplied.** imp
101a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
101b0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
101c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 or sqlite3_os_e
101d0 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 nd().** must ret
101e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
101f0 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 on success and s
10200 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 ome other [error
10210 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 code] upon.** f
10220 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 ailure..*/.SQLIT
10230 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
10240 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
10250 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 _initialize(void
10260 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
10270 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
10280 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
10290 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f n(void);.SQLITE_
102a0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
102b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f TDCALL sqlite3_o
102c0 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 s_init(void);.SQ
102d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
102e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
102f0 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 te3_os_end(void)
10300 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
10310 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 F: Configuring T
10320 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
10330 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 y.**.** The sqli
10340 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 te3_config() int
10350 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
10360 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f o make global co
10370 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 nfiguration.** c
10380 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 hanges to SQLite
10390 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e in order to tun
103a0 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 e SQLite to the
103b0 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f specific needs o
103c0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 f.** the applica
103d0 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 tion. The defau
103e0 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e lt configuration
103f0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
10400 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c for most.** appl
10410 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 ications and so
10420 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
10430 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 usually not nece
10440 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a ssary. It is.**
10450 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 provided to sup
10460 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 port rare applic
10470 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 ations with unus
10480 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ual needs..**.**
10490 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
104a0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
104b0 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 is not threadsaf
104c0 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 e. The applicat
104d0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 ion.** must insu
104e0 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 re that no other
104f0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
10500 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 es are invoked b
10510 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 y other.** threa
10520 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 ds while sqlite3
10530 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e _config() is run
10540 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f ning. Furthermo
10550 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 re, sqlite3_conf
10560 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 ig().** may only
10570 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f be invoked prio
10580 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 r to library ini
10590 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e tialization usin
105a0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e g.** [sqlite3_in
105b0 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 itialize()] or a
105c0 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 fter shutdown by
105d0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
105e0 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 wn()]..** ^If sq
105f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
10600 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b s called after [
10610 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
10620 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 ze()] and before
10630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 .** [sqlite3_shu
10640 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 tdown()] then it
10650 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c will return SQL
10660 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e ITE_MISUSE..** N
10670 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 ote, however, th
10680 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 at ^sqlite3_conf
10690 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c ig() can be call
106a0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
106b0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
106c0 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 ion of an applic
106d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 ation-defined [s
106e0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
106f0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 ]..**.** The fir
10700 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
10710 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
10720 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a is an integer.**
10730 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 [configuration
10740 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 option] that det
10750 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 ermines.** what
10760 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 property of SQLi
10770 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 te is to be conf
10780 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 igured. Subsequ
10790 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a ent arguments.**
107a0 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 vary depending
107b0 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 on the [configur
107c0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a ation option].**
107d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
107e0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 gument..**.** ^W
107f0 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 hen a configurat
10800 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 ion option is se
10810 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 t, sqlite3_confi
10820 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c g() returns [SQL
10830 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 ITE_OK]..** ^If
10840 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e the option is un
10850 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 known or SQLite
10860 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 is unable to set
10870 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 the option.** t
10880 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 hen this routine
10890 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a returns a non-z
108a0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ero [error code]
108b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
108c0 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c int SQLITE_CDECL
108d0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
108e0 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a int, ...);../*.*
108f0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
10900 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 igure database c
10910 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 onnections.** ME
10920 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
10930 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
10940 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 db_config() inte
10950 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
10960 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 make configurat
10970 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ion.** changes t
10980 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f o a [database co
10990 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 nnection]. The
109a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d interface is sim
109b0 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 ilar to.** [sqli
109c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 te3_config()] ex
109d0 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 cept that the ch
109e0 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 anges apply to a
109f0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 single.** [data
10a00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
10a10 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 (specified in t
10a20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
10a30 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 t)..**.** The se
10a40 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
10a50 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
10a60 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 ig(D,V,...) is
10a70 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 the.** [SQLITE_D
10a80 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
10a90 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f E | configuratio
10aa0 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 n verb] - an int
10ab0 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 eger code .** th
10ac0 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 at indicates wha
10ad0 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 t aspect of the
10ae0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
10af0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 tion] is being c
10b00 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 onfigured..** Su
10b10 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e bsequent argumen
10b20 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e ts vary dependin
10b30 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 g on the configu
10b40 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a ration verb..**.
10b50 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c ** ^Calls to sql
10b60 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
10b70 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f return SQLITE_O
10b80 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 K if and only if
10b90 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 .** the call is
10ba0 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 considered succe
10bb0 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ssful..*/.SQLITE
10bc0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
10bd0 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 64 62 CDECL sqlite3_db
10be0 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a _config(sqlite3*
10bf0 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a , int op, ...);.
10c00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
10c10 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 Memory Allocati
10c20 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a on Routines.**.*
10c30 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
10c40 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 this object def
10c50 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 ines the interfa
10c60 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 ce between SQLit
10c70 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 e.** and low-lev
10c80 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 el memory alloca
10c90 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a tion routines..*
10ca0 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 *.** This object
10cb0 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 is used in only
10cc0 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 one place in th
10cd0 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 e SQLite interfa
10ce0 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 ce..** A pointer
10cf0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
10d00 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 of this object i
10d10 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 s the argument t
10d20 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
10d30 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 nfig()] when the
10d40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
10d50 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c ption is.** [SQL
10d60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
10d70 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f C] or [SQLITE_CO
10d80 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e NFIG_GETMALLOC].
10d90 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e .** By creatin
10da0 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 g an instance of
10db0 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 this object.**
10dc0 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 and passing it t
10dd0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
10de0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 g]([SQLITE_CONFI
10df0 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 G_MALLOC]).** du
10e00 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 ring configurati
10e10 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 on, an applicati
10e20 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 on can specify a
10e30 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a n alternative.**
10e40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
10e50 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 on subsystem for
10e60 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 SQLite to use f
10e70 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a or all of its.**
10e80 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 dynamic memory
10e90 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 needs..**.** Not
10ea0 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f e that SQLite co
10eb0 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c mes with several
10ec0 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 [built-in memor
10ed0 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a y allocators].**
10ee0 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 that are perfec
10ef0 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 tly adequate for
10f00 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e the overwhelmin
10f10 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 g majority of ap
10f20 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e plications.** an
10f30 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 d that this obje
10f40 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 ct is only usefu
10f50 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f l to a tiny mino
10f60 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 rity of applicat
10f70 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 ions.** with spe
10f80 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 cialized memory
10f90 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 allocation requi
10fa0 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f rements. This o
10fb0 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f bject is.** also
10fc0 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 used during tes
10fd0 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 ting of SQLite i
10fe0 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 n order to speci
10ff0 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 fy an alternativ
11000 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f e.** memory allo
11010 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c cator that simul
11020 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d ates memory out-
11030 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 of-memory condit
11040 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 ions in.** order
11050 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 to verify that
11060 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 SQLite recovers
11070 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 gracefully from
11080 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f such.** conditio
11090 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d ns..**.** The xM
110a0 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c alloc, xRealloc,
110b0 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f and xFree metho
110c0 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b ds must work lik
110d0 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 e the.** malloc(
110e0 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 ), realloc() and
110f0 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e free() function
11100 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 s from the stand
11110 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a ard C library..*
11120 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e * ^SQLite guaran
11130 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 tees that the se
11140 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
11150 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 .** xRealloc is
11160 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 always a value r
11170 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 eturned by a pri
11180 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e or call to xRoun
11190 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 dup..**.** xSize
111a0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 should return t
111b0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
111c0 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c e of a memory al
111d0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 location.** prev
111e0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 iously obtained
111f0 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 from xMalloc or
11200 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 xRealloc. The a
11210 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a llocated size.**
11220 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 is always at le
11230 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 ast as big as th
11240 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 e requested size
11250 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 but may be larg
11260 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 er..**.** The xR
11270 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 oundup method re
11280 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 turns what would
11290 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 be the allocate
112a0 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d d size of.** a m
112b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
112c0 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 given a particu
112d0 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 lar requested si
112e0 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 ze. Most memory
112f0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 .** allocators r
11300 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 ound up memory a
11310 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 llocations at le
11320 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 ast to the next
11330 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 multiple.** of 8
11340 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f . Some allocato
11350 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 rs round up to a
11360 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 larger multiple
11370 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f or to a power o
11380 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 f 2..** Every me
11390 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
113a0 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 request coming i
113b0 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 n through [sqlit
113c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 e3_malloc()].**
113d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c or [sqlite3_real
113e0 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c loc()] first cal
113f0 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 ls xRoundup. If
11400 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e xRoundup return
11410 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 s 0, .** that ca
11420 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 uses the corresp
11430 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c onding memory al
11440 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c location to fail
11450 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 ..**.** The xIni
11460 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c t method initial
11470 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 izes the memory
11480 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 allocator. For
11490 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d example,.** it m
114a0 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e ight allocate an
114b0 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 y require mutexe
114c0 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 s or initialize
114d0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a internal data.**
114e0 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 structures. Th
114f0 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 e xShutdown meth
11500 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 od is invoked (i
11510 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a ndirectly) by.**
11520 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
11530 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 wn()] and should
11540 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 deallocate any
11550 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 resources acquir
11560 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 ed.** by xInit.
11570 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f The pAppData po
11580 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 inter is used as
11590 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
115a0 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 ter to.** xInit
115b0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a and xShutdown..*
115c0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 *.** SQLite hold
115d0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 s the [SQLITE_MU
115e0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 TEX_STATIC_MASTE
115f0 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 R] mutex when it
11600 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 invokes.** the
11610 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f xInit method, so
11620 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
11630 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 d need not be th
11640 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a readsafe. The.*
11650 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 * xShutdown meth
11660 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 od is only calle
11670 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
11680 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 shutdown()] so i
11690 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 t does.** not ne
116a0 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 ed to be threads
116b0 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 afe either. For
116c0 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f all other metho
116d0 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f ds, SQLite.** ho
116e0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f lds the [SQLITE_
116f0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d MUTEX_STATIC_MEM
11700 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 ] mutex as long
11710 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 as the.** [SQLIT
11720 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
11730 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f US] configuratio
11740 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e n option is turn
11750 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 ed on (which.**
11760 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 it is by default
11770 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 ) and so the met
11780 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 hods are automat
11790 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 ically serialize
117a0 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 d..** However, i
117b0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 f [SQLITE_CONFIG
117c0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 _MEMSTATUS] is d
117d0 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 isabled, then th
117e0 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f e other.** metho
117f0 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 ds must be threa
11800 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 dsafe or else ma
11810 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 ke their own arr
11820 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a angements for.**
11830 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a serialization..
11840 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
11850 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 l never invoke x
11860 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e Init() more than
11870 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e once without an
11880 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 intervening.**
11890 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 call to xShutdow
118a0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 n()..*/.typedef
118b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
118c0 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 em_methods sqlit
118d0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a e3_mem_methods;.
118e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
118f0 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 em_methods {. v
11900 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 oid *(*xMalloc)(
11910 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a int); /*
11920 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
11930 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 on function */.
11940 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 void (*xFree)(v
11950 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
11960 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 /* Free a prior
11970 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
11980 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 void *(*xRealloc
11990 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f )(void*,int); /
119a0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f * Resize an allo
119b0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
119c0 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b (*xSize)(void*);
119d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 /* Re
119e0 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 turn the size of
119f0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
11a00 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 /. int (*xRound
11a10 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 up)(int);
11a20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 /* Round up r
11a30 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 equest size to a
11a40 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a llocation size *
11a50 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 /. int (*xInit)
11a60 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
11a70 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 /* Initialize
11a80 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
11a90 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
11aa0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 (*xShutdown)(voi
11ab0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 d*); /* Dei
11ac0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
11ad0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
11ae0 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
11af0 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 ta;
11b00 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 /* Argument t
11b10 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 o xInit() and xS
11b20 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a hutdown() */.};.
11b30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
11b40 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f Configuration O
11b50 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 ptions.** KEYWOR
11b60 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 DS: {configurati
11b70 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a on option}.**.**
11b80 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
11b90 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 are the availab
11ba0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 le integer confi
11bb0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
11bc0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 that.** can be
11bd0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
11be0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
11bf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
11c00 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
11c10 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 ..**.** New conf
11c20 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
11c30 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
11c40 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
11c50 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
11c60 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 Existing configu
11c70 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
11c80 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 ight be disconti
11c90 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 nued. Applicati
11ca0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 ons.** should ch
11cb0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 eck the return c
11cc0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ode from [sqlite
11cd0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 3_config()] to m
11ce0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a ake sure that.**
11cf0 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 the call worked
11d00 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
11d10 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
11d20 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
11d30 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
11d40 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
11d50 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
11d60 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
11d70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
11d80 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
11d90 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b **.** <dl>.** [[
11da0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
11db0 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 NGLETHREAD]] <dt
11dc0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
11dd0 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e INGLETHREAD</dt>
11de0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
11df0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
11e00 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
11e10 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
11e20 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
11e30 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e ing mode] to Sin
11e40 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 gle-thread. In
11e50 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 other words, it
11e60 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 disables.** all
11e70 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 mutexing and put
11e80 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 s SQLite into a
11e90 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 mode where it ca
11ea0 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a n only be used.*
11eb0 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 * by a single th
11ec0 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 read. ^If SQLi
11ed0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
11ee0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
11ef0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
11f00 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
11f10 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
11f20 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
11f30 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
11f40 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 ble to change th
11f50 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
11f60 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 e] from its defa
11f70 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 ult.** value of
11f80 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e Single-thread an
11f90 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f d so [sqlite3_co
11fa0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 nfig()] will ret
11fb0 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urn .** [SQLITE_
11fc0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 ERROR] if called
11fd0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
11fe0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
11ff0 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 READ.** configur
12000 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 ation option.</d
12010 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
12020 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
12030 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 READ]] <dt>SQLIT
12040 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
12050 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 READ</dt>.** <dd
12060 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
12070 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
12080 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f option. ^This o
12090 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
120a0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 * [threading mod
120b0 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 e] to Multi-thre
120c0 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f ad. In other wo
120d0 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 rds, it disables
120e0 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 .** mutexing on
120f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
12100 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 tion] and [prepa
12110 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
12120 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 bjects..** The a
12130 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 pplication is re
12140 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 sponsible for se
12150 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 rializing access
12160 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 to.** [database
12170 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e connections] an
12180 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
12190 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 ements]. But ot
121a0 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 her mutexes.** a
121b0 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 re enabled so th
121c0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 at SQLite will b
121d0 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e e safe to use in
121e0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 a multi-threade
121f0 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 d.** environment
12200 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 as long as no t
12210 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d wo threads attem
12220 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 pt to use the sa
12230 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 me.** [database
12240 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 connection] at t
12250 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e he same time. ^
12260 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
12270 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
12280 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
12290 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
122a0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
122b0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
122c0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f then.** it is no
122d0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 t possible to se
122e0 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 t the Multi-thre
122f0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ad [threading mo
12300 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 de] and.** [sqli
12310 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
12320 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
12330 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c E_ERROR] if call
12340 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 ed with the.** S
12350 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
12360 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 TITHREAD configu
12370 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
12380 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
12390 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
123a0 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 IZED]] <dt>SQLIT
123b0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
123c0 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ZED</dt>.** <dd>
123d0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
123e0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
123f0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 ption. ^This op
12400 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
12410 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
12420 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e ] to Serialized.
12430 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
12440 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 this option ena
12450 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 bles.** all mute
12460 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 xes including th
12470 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d e recursive.** m
12480 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 utexes on [datab
12490 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
124a0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
124b0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
124c0 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 ..** In this mod
124d0 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 e (which is the
124e0 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c default when SQL
124f0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
12500 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f with.** [SQLITE_
12510 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 THREADSAFE=1]) t
12520 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
12530 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 y will itself se
12540 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a rialize access.*
12550 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 * to [database c
12560 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 onnections] and
12570 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
12580 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 ents] so that th
12590 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e e.** application
125a0 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 is free to use
125b0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 the same [databa
125c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
125d0 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 r the.** same [p
125e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
125f0 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 t] in different
12600 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 threads at the s
12610 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 ame time..** ^If
12620 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
12630 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
12640 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
12650 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
12660 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
12670 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
12680 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
12690 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 possible to set
126a0 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b the Serialized [
126b0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
126c0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
126d0 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 config()] will r
126e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 eturn [SQLITE_ER
126f0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 ROR] if called w
12700 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 ith the.** SQLIT
12710 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
12720 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ZED configuratio
12730 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a n option.</dd>.*
12740 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
12750 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 NFIG_MALLOC]] <d
12760 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
12770 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
12780 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 dd> ^(The SQLITE
12790 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f _CONFIG_MALLOC o
127a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
127b0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
127c0 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 ich is .** a poi
127d0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
127e0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
127f0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
12800 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 structure..** T
12810 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 he argument spec
12820 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 ifies.** alterna
12830 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d tive low-level m
12840 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
12850 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
12860 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 used in place of
12870 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 .** the memory a
12880 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
12890 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 es built into SQ
128a0 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 Lite.)^ ^SQLite
128b0 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e makes.** its own
128c0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
128d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
128e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
128f0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
12900 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 ure.** before th
12910 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e [sqlite3_confi
12920 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e g()] call return
12930 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b s.</dd>.**.** [[
12940 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
12950 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 TMALLOC]] <dt>SQ
12960 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
12970 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ALLOC</dt>.** <d
12980 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f d> ^(The SQLITE_
12990 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
129a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
129b0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
129c0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f which.** is a po
129d0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
129e0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
129f0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
12a00 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 ] structure..**
12a10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
12a20 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
12a30 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
12a40 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
12a50 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f tly defined memo
12a60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
12a70 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 utines.)^.** Thi
12a80 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 s option can be
12a90 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 used to overload
12aa0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d the default mem
12ab0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
12ac0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 * routines with
12ad0 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 a wrapper that s
12ae0 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 imulations memor
12af0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
12b00 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b lure or.** track
12b10 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 s memory usage,
12b20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 for example. </d
12b30 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
12b40 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
12b50 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f US]] <dt>SQLITE_
12b60 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
12b70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
12b80 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
12b90 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f _MEMSTATUS optio
12ba0 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 n takes single a
12bb0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 rgument of type
12bc0 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 int,.** interpre
12bd0 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e ted as a boolean
12be0 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 , which enables
12bf0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 or disables the
12c00 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a collection of.**
12c10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
12c20 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e on statistics. ^
12c30 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c (When memory all
12c40 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
12c50 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c cs are.** disabl
12c60 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e ed, the followin
12c70 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 g SQLite interfa
12c80 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f ces become non-o
12c90 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 perational:.**
12ca0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 <ul>.** <li>
12cb0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
12cc0 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 used()].** <li
12cd0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 > [sqlite3_memor
12ce0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a y_highwater()].*
12cf0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
12d00 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
12d10 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e t64()].** <li>
12d20 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 [sqlite3_status
12d30 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 64()].** </ul>
12d40 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c )^.** ^Memory al
12d50 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 location statist
12d60 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 ics are enabled
12d70 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 by default unles
12d80 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 s SQLite is.** c
12d90 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 ompiled with [SQ
12da0 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d LITE_DEFAULT_MEM
12db0 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 STATUS]=0 in whi
12dc0 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a ch case memory.*
12dd0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 * allocation sta
12de0 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 tistics are disa
12df0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e bled by default.
12e00 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
12e10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
12e20 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 SCRATCH]] <dt>SQ
12e30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
12e40 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TCH</dt>.** <dd>
12e50 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^The SQLITE_CON
12e60 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 FIG_SCRATCH opti
12e70 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 on specifies a s
12e80 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 tatic memory buf
12e90 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 fer.** that SQLi
12ea0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 te can use for s
12eb0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 cratch memory.
12ec0 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65 ^(There are thre
12ed0 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 e arguments.** t
12ee0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f o SQLITE_CONFIG_
12ef0 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e SCRATCH: A poin
12f00 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a ter an 8-byte.**
12f10 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 aligned memory
12f20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 buffer from whic
12f30 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c h the scratch al
12f40 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 locations will b
12f50 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 e.** drawn, the
12f60 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 size of each scr
12f70 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 atch allocation
12f80 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 (sz),.** and the
12f90 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
12fa0 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 of scratch alloc
12fb0 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a ations (N).)^.**
12fc0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
12fd0 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f ent must be a po
12fe0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 inter to an 8-by
12ff0 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 te aligned buffe
13000 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 r.** of at least
13010 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d sz*N bytes of m
13020 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 emory..** ^SQLit
13030 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d e will not use m
13040 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 ore than one scr
13050 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 atch buffers per
13060 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c thread..** ^SQL
13070 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 ite will never r
13080 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68 equest a scratch
13090 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 buffer that is
130a0 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 more than 6.** t
130b0 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 imes the databas
130c0 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 e page size..**
130d0 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 ^If SQLite needs
130e0 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 needs additiona
130f0 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d l.** scratch mem
13100 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 ory beyond what
13110 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 is provided by t
13120 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f his configuratio
13130 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a n option, then .
13140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
13150 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 oc()] will be us
13160 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 ed to obtain the
13170 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c memory needed.<
13180 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 p>.** ^When the
13190 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 application prov
131a0 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 ides any amount
131b0 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 of scratch memor
131c0 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 y using.** SQLIT
131d0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
131e0 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 , SQLite avoids
131f0 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 unnecessary larg
13200 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 e.** [sqlite3_ma
13210 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 lloc|heap alloca
13220 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 tions]..** This
13230 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e can help [Robson
13240 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d proof|prevent m
13250 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
13260 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 failures] due t
13270 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 o heap.** fragme
13280 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d ntation in low-m
13290 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 emory embedded s
132a0 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e ystems..** </dd>
132b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
132c0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
132d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
132e0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f NFIG_PAGECACHE</
132f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 dt>.** <dd> ^The
13300 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
13310 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 AGECACHE option
13320 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 specifies a stat
13330 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ic memory buffer
13340 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 .** that SQLite
13350 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 can use for the
13360 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 database page ca
13370 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 che with the def
13380 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 ault page.** cac
13390 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
133a0 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e n. .** This con
133b0 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c figuration shoul
133c0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 d not be used if
133d0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
133e0 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 define page.** c
133f0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
13400 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 ion is loaded us
13410 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
13420 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a CONFIG_PCACHE2].
13430 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
13440 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 option..** ^The
13450 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
13460 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 uments to SQLITE
13470 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
13480 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a E: A pointer to.
13490 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 ** 8-byte aligne
134a0 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 d.** memory, the
134b0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 size of each pa
134c0 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 ge buffer (sz),
134d0 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f and the number o
134e0 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 f pages (N)..**
134f0 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 The sz argument
13500 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 should be the si
13510 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 ze of the larges
13520 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a t database page.
13530 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 ** (a power of t
13540 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 wo between 512 a
13550 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 nd 65536) plus s
13560 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20 ome extra bytes
13570 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 for each.** page
13580 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e header. ^The n
13590 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 umber of extra b
135a0 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 ytes needed by t
135b0 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a he page header.*
135c0 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 * can be determi
135d0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 ned using the [S
135e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
135f0 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f CHE_HDRSZ] optio
13600 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 n .** to [sqlite
13610 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 3_config()]..**
13620 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c ^It is harmless,
13630 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 apart from the
13640 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a wasted memory,.*
13650 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 * for the sz par
13660 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 ameter to be lar
13670 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 ger than necessa
13680 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a ry. The first.*
13690 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c * argument shoul
136a0 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 d pointer to an
136b0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 8-byte aligned b
136c0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74 lock of memory t
136d0 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61 hat.** is at lea
136e0 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 st sz*N bytes of
136f0 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69 memory, otherwi
13700 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 se subsequent be
13710 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 havior is.** und
13720 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 efined..** ^SQLi
13730 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 te will use the
13740 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 memory provided
13750 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 by the first arg
13760 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 ument to satisfy
13770 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e its.** memory n
13780 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 eeds for the fir
13790 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 st N pages that
137a0 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 it adds to cache
137b0 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 . ^If additiona
137c0 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 l.** page cache
137d0 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 memory is needed
137e0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 beyond what is
137f0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 provided by this
13800 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a option, then.**
13810 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 SQLite goes to
13820 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
13830 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 )] for the addit
13840 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 ional storage sp
13850 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ace.</dd>.**.**
13860 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
13870 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 HEAP]] <dt>SQLIT
13880 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 E_CONFIG_HEAP</d
13890 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 t>.** <dd> ^The
138a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
138b0 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 AP option specif
138c0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d ies a static mem
138d0 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 ory buffer .** t
138e0 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
138f0 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 use for all of i
13900 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 ts dynamic memor
13910 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
13920 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f ds.** beyond tho
13930 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 se provided for
13940 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 by [SQLITE_CONFI
13950 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a G_SCRATCH] and.*
13960 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
13970 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 _PAGECACHE]..**
13980 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
13990 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 IG_HEAP option i
139a0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 s only available
139b0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
139c0 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 mpiled.** with e
139d0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e ither [SQLITE_EN
139e0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 ABLE_MEMSYS3] or
139f0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
13a00 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 MEMSYS5] and ret
13a10 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urns.** [SQLITE_
13a20 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 ERROR] if invoke
13a30 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 d otherwise..**
13a40 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 ^There are three
13a50 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 arguments to SQ
13a60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
13a70 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 :.** An 8-byte a
13a80 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 ligned pointer t
13a90 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a o the memory,.**
13aa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
13ab0 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f ytes in the memo
13ac0 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 ry buffer, and t
13ad0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 he minimum alloc
13ae0 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e ation size..** ^
13af0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 If the first poi
13b00 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 nter (the memory
13b10 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c pointer) is NUL
13b20 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 L, then SQLite r
13b30 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 everts.** to usi
13b40 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d ng its default m
13b50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
13b60 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c (the system mall
13b70 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 oc() implementat
13b80 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 ion),.** undoing
13b90 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 any prior invoc
13ba0 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 ation of [SQLITE
13bb0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e _CONFIG_MALLOC].
13bc0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d ^If the.** mem
13bd0 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e ory pointer is n
13be0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 ot NULL then the
13bf0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d alternative mem
13c00 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 ory.** allocator
13c10 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 is engaged to h
13c20 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c andle all of SQL
13c30 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ites memory allo
13c40 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a cation needs..**
13c50 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 The first point
13c60 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 er (the memory p
13c70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 ointer) must be
13c80 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d aligned to an 8-
13c90 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 byte.** boundary
13ca0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 or subsequent b
13cb0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 ehavior of SQLit
13cc0 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 e will be undefi
13cd0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 ned..** The mini
13ce0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 mum allocation s
13cf0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 ize is capped at
13d00 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 2**12. Reasonab
13d10 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 le values.** for
13d20 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
13d30 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 ocation size are
13d40 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2**5 through 2*
13d50 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b *8.</dd>.**.** [
13d60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
13d70 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 UTEX]] <dt>SQLIT
13d80 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f E_CONFIG_MUTEX</
13d90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
13da0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
13db0 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b MUTEX option tak
13dc0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
13dd0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a ment which is a.
13de0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e ** pointer to an
13df0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
13e00 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
13e10 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
13e20 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d re..** The argum
13e30 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c ent specifies al
13e40 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 ternative low-le
13e50 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e vel mutex routin
13e60 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a es to be used.**
13e70 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 in place the mu
13e80 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 tex routines bui
13e90 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 lt into SQLite.)
13ea0 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 ^ ^SQLite makes
13eb0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 a copy of.** th
13ec0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
13ed0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
13ee0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
13ef0 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 re before the ca
13f00 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
13f10 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 3_config()] retu
13f20 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 rns. ^If SQLite
13f30 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
13f40 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
13f50 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
13f60 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
13f70 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
13f80 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 ption then.** th
13f90 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e e entire mutexin
13fa0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f g subsystem is o
13fb0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 mitted from the
13fc0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 build and hence
13fd0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c calls to.** [sql
13fe0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
13ff0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 ith the SQLITE_C
14000 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 ONFIG_MUTEX conf
14010 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
14020 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 will.** return
14030 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c [SQLITE_ERROR].<
14040 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
14050 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
14060 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 TEX]] <dt>SQLITE
14070 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
14080 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
14090 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
140a0 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f G_GETMUTEX optio
140b0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
140c0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a argument which.
140d0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ** is a pointer
140e0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
140f0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
14100 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 utex_methods] st
14110 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a ructure. The.**
14120 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
14130 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 methods].** stru
14140 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 cture is filled
14150 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 with the current
14160 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 ly defined mutex
14170 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 routines.)^.**
14180 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 This option can
14190 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c be used to overl
141a0 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 oad the default
141b0 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e mutex allocation
141c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 .** routines wit
141d0 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 h a wrapper used
141e0 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 to track mutex
141f0 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 usage for perfor
14200 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 mance.** profili
14210 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 ng or testing, f
14220 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 or example. ^I
14230 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
14240 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
14250 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
14260 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
14270 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
14280 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
14290 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 hen.** the entir
142a0 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 e mutexing subsy
142b0 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 stem is omitted
142c0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 from the build a
142d0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 nd hence calls t
142e0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
142f0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 nfig()] with the
14300 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
14310 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 ETMUTEX configur
14320 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c ation option wil
14330 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c l.** return [SQL
14340 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e ITE_ERROR].</dd>
14350 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
14360 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
14370 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
14380 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
14390 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
143a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
143b0 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e LOOKASIDE option
143c0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d takes two argum
143d0 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d ents that determ
143e0 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 ine.** the defau
143f0 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 lt size of looka
14400 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 side memory on e
14410 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f ach [database co
14420 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 nnection]..** Th
14430 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
14440 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 is the.** size
14450 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 of each lookasid
14460 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e e buffer slot an
14470 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 d the second is
14480 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
14490 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 slots allocated
144a0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 to each databas
144b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 e connection.)^
144c0 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ^(SQLITE_CONFIG
144d0 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 _LOOKASIDE.** se
144e0 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c ts the <i>defaul
144f0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 t</i> lookaside
14500 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 size. The [SQLIT
14510 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
14520 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 SIDE].** option
14530 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 to [sqlite3_db_c
14540 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 onfig()] can be
14550 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 used to change t
14560 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 he lookaside.**
14570 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e configuration on
14580 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e individual conn
14590 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e ections.)^ </dd>
145a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
145b0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d CONFIG_PCACHE2]]
145c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
145d0 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a IG_PCACHE2</dt>.
145e0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
145f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
14600 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 HE2 option takes
14610 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
14620 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 nt which is .**
14630 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
14640 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
14650 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 methods2] object
14660 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 . This object s
14670 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 pecifies.** the
14680 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 interface to a c
14690 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 ustom page cache
146a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
146b0 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 )^.** ^SQLite ma
146c0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
146d0 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 e [sqlite3_pcach
146e0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 e_methods2] obje
146f0 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ct.</dd>.**.** [
14700 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
14710 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e ETPCACHE2]] <dt>
14720 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
14730 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a TPCACHE2</dt>.**
14740 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 <dd> ^(The SQLI
14750 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
14760 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 CHE2 option take
14770 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
14780 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ent which.** is
14790 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
147a0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
147b0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 methods2] object
147c0 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 . SQLite copies
147d0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 of.** the curre
147e0 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d nt page cache im
147f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 plementation int
14800 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e o that object.)^
14810 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
14820 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
14830 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
14840 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a NFIG_LOG</dt>.**
14850 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 <dd> The SQLITE
14860 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 _CONFIG_LOG opti
14870 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f on is used to co
14880 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 nfigure the SQLi
14890 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 te.** global [er
148a0 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 ror log]..** (^T
148b0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
148c0 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 _LOG option take
148d0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a s two arguments:
148e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a a pointer to a.
148f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 ** function with
14900 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 a call signatur
14910 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 e of void(*)(voi
14920 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
14930 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 r*), .** and a p
14940 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 ointer to void.
14950 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e ^If the function
14960 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
14970 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 NULL, it is.** i
14980 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 nvoked by [sqlit
14990 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f e3_log()] to pro
149a0 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e cess each loggin
149b0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 g event. ^If th
149c0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f e.** function po
149d0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 inter is NULL, t
149e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 he [sqlite3_log(
149f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 )] interface bec
14a00 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a omes a no-op..**
14a10 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 ^The void point
14a20 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 er that is the s
14a30 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
14a40 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f o SQLITE_CONFIG_
14a50 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 LOG is.** passed
14a60 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 through as the
14a70 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
14a80 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 to the applicati
14a90 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 on-defined logge
14aa0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 r.** function wh
14ab0 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 enever that func
14ac0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e tion is invoked.
14ad0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 ^The second pa
14ae0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 rameter to.** th
14af0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f e logger functio
14b00 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 n is a copy of t
14b10 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
14b20 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 er to the corres
14b30 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 ponding.** [sqli
14b40 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 te3_log()] call
14b50 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 and is intended
14b60 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 to be a [result
14b70 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b code] or an.** [
14b80 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
14b90 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 code]. ^The thi
14ba0 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 rd parameter pas
14bb0 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 sed to the logge
14bc0 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 r is.** log mess
14bd0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 age after format
14be0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 ting via [sqlite
14bf0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 3_snprintf()]..*
14c00 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 * The SQLite log
14c10 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 ging interface i
14c20 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b s not reentrant;
14c30 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 the logger func
14c40 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 tion.** supplied
14c50 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
14c60 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 ion must not inv
14c70 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 oke any SQLite i
14c80 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 nterface..** In
14c90 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 a multi-threaded
14ca0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 application, th
14cb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
14cc0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 fined logger.**
14cd0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 function must be
14ce0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 threadsafe. </d
14cf0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
14d00 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c E_CONFIG_URI]] <
14d10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
14d20 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 _URI.** <dd>^(Th
14d30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
14d40 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 URI option takes
14d50 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
14d60 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a nt of type int..
14d70 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 ** If non-zero,
14d80 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e then URI handlin
14d90 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e g is globally en
14da0 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 abled. If the pa
14db0 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c rameter is zero,
14dc0 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e .** then URI han
14dd0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c dling is globall
14de0 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 y disabled.)^ ^I
14df0 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 f URI handling i
14e00 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e s globally.** en
14e10 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e abled, all filen
14e20 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b ames passed to [
14e30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
14e40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
14e50 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 2()],.** [sqlite
14e60 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 3_open16()] or.*
14e70 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 * specified as p
14e80 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 art of [ATTACH]
14e90 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 commands are int
14ea0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 erpreted as URIs
14eb0 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 , regardless.**
14ec0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
14ed0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 t the [SQLITE_OP
14ee0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 EN_URI] flag is
14ef0 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 set when the dat
14f00 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
14f10 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e ion is opened. ^
14f20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c If it is globall
14f30 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 y disabled, file
14f40 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c names are.** onl
14f50 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 y interpreted as
14f60 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c URIs if the SQL
14f70 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 ITE_OPEN_URI fla
14f80 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 g is set when th
14f90 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
14fa0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e nnection is open
14fb0 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 ed. ^(By default
14fc0 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 , URI handling i
14fd0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 s globally.** di
14fe0 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 sabled. The defa
14ff0 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 ult value may be
15000 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 changed by comp
15010 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a iling with the.*
15020 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 * [SQLITE_USE_UR
15030 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 I] symbol define
15040 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d.)^.**.** [[SQL
15050 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
15060 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d ING_INDEX_SCAN]]
15070 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
15080 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 IG_COVERING_INDE
15090 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 X_SCAN.** <dd>^T
150a0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
150b0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f _COVERING_INDEX_
150c0 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 SCAN option take
150d0 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 s a single integ
150e0 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 er.** argument w
150f0 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 hich is interpre
15100 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e ted as a boolean
15110 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 in order to ena
15120 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a ble or disable.*
15130 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 * the use of cov
15140 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f ering indices fo
15150 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 r full table sca
15160 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 ns in the query
15170 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 optimizer..** ^T
15180 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 he default setti
15190 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 ng is determined
151a0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 .** by the [SQLI
151b0 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e TE_ALLOW_COVERIN
151c0 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f G_INDEX_SCAN] co
151d0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
151e0 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a n, or is "on".**
151f0 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 if that compile
15200 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 -time option is
15210 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 omitted..** The
15220 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 ability to disab
15230 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f le the use of co
15240 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 vering indices f
15250 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 or full table sc
15260 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 ans.** is becaus
15270 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 e some incorrect
15280 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 ly coded legacy
15290 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 applications mig
152a0 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a ht malfunction.*
152b0 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d * when the optim
152c0 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c ization is enabl
152d0 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 ed. Providing t
152e0 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a he ability to.**
152f0 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 disable the opt
15300 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 imization allows
15310 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 the older, bugg
15320 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f y application co
15330 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 de to work.** wi
15340 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 thout change eve
15350 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 n with newer ver
15360 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e sions of SQLite.
15370 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
15380 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 CONFIG_PCACHE]]
15390 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
153a0 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c GETPCACHE]].** <
153b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
153c0 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 _PCACHE and SQLI
153d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
153e0 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 CHE.** <dd> Thes
153f0 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 e options are ob
15400 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c solete and shoul
15410 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 d not be used by
15420 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 new code..** Th
15430 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 ey are retained
15440 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f for backwards co
15450 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 mpatibility but
15460 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a are now no-ops..
15470 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ** </dd>.**.** [
15480 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
15490 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 QLLOG]].** <dt>S
154a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c QLITE_CONFIG_SQL
154b0 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 LOG.** <dd>This
154c0 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 option is only a
154d0 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 vailable if sqli
154e0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
154f0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
15500 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 TE_ENABLE_SQLLOG
15510 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 ] pre-processor
15520 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 macro defined. T
15530 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
15540 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 t should.** be a
15550 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 pointer to a fu
15560 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 nction of type v
15570 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
15580 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 ite3*,const char
15590 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 *, int)..** The
155a0 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 second should be
155b0 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 of type (void*)
155c0 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 . The callback i
155d0 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 s invoked by the
155e0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 library.** in t
155f0 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 hree separate ci
15600 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 rcumstances, ide
15610 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 ntified by the v
15620 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 alue passed as t
15630 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 he.** fourth par
15640 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 ameter. If the f
15650 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
15660 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 is 0, then the d
15670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
15680 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 on.** passed as
15690 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
156a0 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 ent has just bee
156b0 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 n opened. The th
156c0 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ird argument.**
156d0 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 points to a buff
156e0 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 er containing th
156f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 e name of the ma
15700 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 in database file
15710 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 . If the.** four
15720 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
15730 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 1, then the SQL
15740 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 statement that t
15750 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
15760 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 er.** points to
15770 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 has just been ex
15780 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 ecuted. Or, if t
15790 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
157a0 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a ter is 2, then.*
157b0 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e * the connection
157c0 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 being passed as
157d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
157e0 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 meter is being c
157f0 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 losed. The.** th
15800 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
15810 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 passed NULL In
15820 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 this case. An e
15830 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 xample of using
15840 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 this.** configur
15850 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e ation option can
15860 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 be seen in the
15870 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 "test_sqllog.c"
15880 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a source file in.*
15890 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 * the canonical
158a0 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 SQLite source tr
158b0 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ee.</dd>.**.** [
158c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
158d0 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 MAP_SIZE]].** <d
158e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
158f0 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 MMAP_SIZE.** <dd
15900 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f >^SQLITE_CONFIG_
15910 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 MMAP_SIZE takes
15920 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 two 64-bit integ
15930 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 er (sqlite3_int6
15940 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 4) values.** tha
15950 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c t are the defaul
15960 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 t mmap size limi
15970 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 t (the default s
15980 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 etting for.** [P
15990 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d RAGMA mmap_size]
159a0 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 ) and the maximu
159b0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 m allowed mmap s
159c0 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 ize limit..** ^T
159d0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 he default setti
159e0 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 ng can be overri
159f0 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 dden by each dat
15a00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
15a10 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 using.** either
15a20 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 the [PRAGMA mma
15a30 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c p_size] command,
15a40 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 or by using the
15a50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 .** [SQLITE_FCNT
15a60 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c L_MMAP_SIZE] fil
15a70 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 e control. ^(Th
15a80 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 e maximum allowe
15a90 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 d mmap size.** w
15aa0 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 ill be silently
15ab0 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 truncated if nec
15ac0 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 essary so that i
15ad0 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 t does not excee
15ae0 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 d the.** compile
15af0 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d -time maximum mm
15b00 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 ap size set by t
15b10 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 he.** [SQLITE_MA
15b20 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d X_MMAP_SIZE] com
15b30 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
15b40 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 .)^.** ^If eithe
15b50 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 r argument to th
15b60 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 is option is neg
15b70 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 ative, then that
15b80 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 argument is.**
15b90 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 changed to its c
15ba0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 ompile-time defa
15bb0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c ult..**.** [[SQL
15bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 ITE_CONFIG_WIN32
15bd0 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c _HEAPSIZE]].** <
15be0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
15bf0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a _WIN32_HEAPSIZE.
15c00 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 ** <dd>^The SQLI
15c10 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f TE_CONFIG_WIN32_
15c20 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 HEAPSIZE option
15c30 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c is only availabl
15c40 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a e if SQLite is.*
15c50 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 * compiled for W
15c60 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 indows with the
15c70 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 [SQLITE_WIN32_MA
15c80 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 LLOC] pre-proces
15c90 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 sor macro.** def
15ca0 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f ined. ^SQLITE_CO
15cb0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 NFIG_WIN32_HEAPS
15cc0 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 IZE takes a 32-b
15cd0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 it unsigned inte
15ce0 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 ger value.** tha
15cf0 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 t specifies the
15d00 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 maximum size of
15d10 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70 the created heap
15d20 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ..**.** [[SQLITE
15d30 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 _CONFIG_PCACHE_H
15d40 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 DRSZ]].** <dt>SQ
15d50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
15d60 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e HE_HDRSZ.** <dd>
15d70 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
15d80 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 IG_PCACHE_HDRSZ
15d90 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
15da0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 ingle parameter
15db0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f which.** is a po
15dc0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
15dd0 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 ger and writes i
15de0 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 nto that integer
15df0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
15e00 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 xtra.** bytes pe
15e10 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20 r page required
15e20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e for each page in
15e30 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
15e40 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 PAGECACHE]..** T
15e50 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 he amount of ext
15e60 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65 ra space require
15e70 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 d can change dep
15e80 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f ending on the co
15e90 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 mpiler,.** targe
15ea0 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 t platform, and
15eb0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a SQLite version..
15ec0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
15ed0 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a ONFIG_PMASZ]].**
15ee0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
15ef0 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e IG_PMASZ.** <dd>
15f00 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
15f10 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 IG_PMASZ option
15f20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 takes a single p
15f30 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a arameter which.*
15f40 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 * is an unsigned
15f50 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 integer and set
15f60 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 s the "Minimum P
15f70 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 MA Size" for the
15f80 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a multithreaded.*
15f90 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 * sorter to that
15fa0 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 integer. The d
15fb0 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 efault minimum P
15fc0 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 MA Size is set b
15fd0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 y the.** [SQLITE
15fe0 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 _SORTER_PMASZ] c
15ff0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
16000 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 on. New threads
16010 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a are launched.**
16020 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f to help with so
16030 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 rt operations wh
16040 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 en multithreaded
16050 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 sorting.** is e
16060 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 nabled (using th
16070 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 e [PRAGMA thread
16080 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 s] command) and
16090 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f the amount of co
160a0 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 ntent.** to be s
160b0 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68 orted exceeds th
160c0 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 e page size time
160d0 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 s the minimum of
160e0 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 the.** [PRAGMA
160f0 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 cache_size] sett
16100 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c ing and this val
16110 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a ue..** </dl>.*/.
16120 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16130 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
16140 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f AD 1 /* nil */
16150 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16160 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
16170 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a AD 2 /* nil *
16180 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16190 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a _CONFIG_SERIALIZ
161a0 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 ED 3 /* nil
161b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
161c0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 E_CONFIG_MALLOC
161d0 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 4 /* sql
161e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
161f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
16200 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
16210 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 LLOC 5 /* s
16220 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
16230 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
16240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
16250 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a ATCH 6 /*
16260 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 void*, int sz,
16270 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 int N */.#define
16280 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
16290 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 AGECACHE 7
162a0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a /* void*, int sz
162b0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 , int N */.#defi
162c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
162d0 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 _HEAP 8
162e0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
162f0 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a nByte, int min *
16300 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16310 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
16320 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c S 9 /* bool
16330 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ean */.#define S
16340 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
16350 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a EX 10 /*
16360 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
16370 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
16380 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16390 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 _GETMUTEX 11
163a0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 /* sqlite3_mut
163b0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f ex_methods* */./
163c0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c * previously SQL
163d0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b ITE_CONFIG_CHUNK
163e0 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 ALLOC 12 which i
163f0 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f s now unused. */
16400 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .#define SQLITE
16410 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
16420 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 E 13 /* int
16430 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
16440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
16450 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a CHE 14 /*
16460 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e no-op */.#defin
16470 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16480 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 GETPCACHE 15
16490 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 /* no-op */.#de
164a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
164b0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 IG_LOG
164c0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 16 /* xFunc, vo
164d0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 id* */.#define S
164e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
164f0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 17 /*
16500 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
16510 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
16520 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f ACHE2 18 /
16530 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 * sqlite3_pcache
16540 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 _methods2* */.#d
16550 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
16560 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 FIG_GETPCACHE2
16570 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 19 /* sqlite3_
16580 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a pcache_methods2*
16590 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
165a0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 TE_CONFIG_COVERI
165b0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 NG_INDEX_SCAN 20
165c0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 /* int */.#def
165d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
165e0 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 G_SQLLOG 2
165f0 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 1 /* xSqllog, v
16600 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 oid* */.#define
16610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d SQLITE_CONFIG_MM
16620 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f AP_SIZE 22 /
16630 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c * sqlite3_int64,
16640 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
16650 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16660 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 _CONFIG_WIN32_HE
16670 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 APSIZE 23
16680 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a /* int nByte */.
16690 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
166a0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 ONFIG_PCACHE_HDR
166b0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a SZ 24 /*
166c0 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 int *psz */.#de
166d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
166e0 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 IG_PMASZ
166f0 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 25 /* un
16700 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 signed int szPma
16710 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
16720 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f REF: Database Co
16730 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 nnection Configu
16740 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a ration Options.*
16750 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
16760 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 ants are the ava
16770 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 ilable integer c
16780 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
16790 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e ions that.** can
167a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
167b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
167c0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 t to the [sqlite
167d0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 3_db_config()] i
167e0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
167f0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f New configuratio
16800 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 n options may be
16810 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
16820 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
16830 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 ite..** Existing
16840 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
16850 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 ptions might be
16860 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 discontinued. A
16870 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
16880 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 hould check the
16890 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d return code from
168a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
168b0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 fig()] to make s
168c0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ure that.** the
168d0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 call worked. ^T
168e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 he [sqlite3_db_c
168f0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 onfig()] interfa
16900 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 ce will return a
16910 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 .** non-zero [er
16920 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 ror code] if a d
16930 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 iscontinued or u
16940 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 nsupported confi
16950 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a guration option.
16960 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a ** is invoked..*
16970 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
16980 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
16990 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a _LOOKASIDE</dt>.
169a0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
169b0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 tion takes three
169c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
169d0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 ments that deter
169e0 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f mine the .** [lo
169f0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
16a00 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 llocator] config
16a10 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 uration for the
16a20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
16a30 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 tion]..** ^The f
16a40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 irst argument (t
16a50 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
16a60 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 er to [sqlite3_d
16a70 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 b_config()] is a
16a80 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 .** pointer to a
16a90 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
16aa0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 o use for lookas
16ab0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e ide memory..** ^
16ac0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
16ad0 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c nt after the SQL
16ae0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
16af0 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d KASIDE verb.** m
16b00 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 ay be NULL in wh
16b10 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 ich case SQLite
16b20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 will allocate th
16b30 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 e.** lookaside b
16b40 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 uffer itself usi
16b50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ng [sqlite3_mall
16b60 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f oc()]. ^The seco
16b70 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
16b80 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 he.** size of ea
16b90 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 ch lookaside buf
16ba0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 fer slot. ^The
16bb0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
16bc0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
16bd0 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 ** slots. The s
16be0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 ize of the buffe
16bf0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 r in the first a
16c00 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
16c10 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 greater than.**
16c20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 or equal to the
16c30 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 product of the s
16c40 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 econd and third
16c50 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 arguments. The
16c60 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 buffer.** must b
16c70 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
16c80 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 8-byte boundary.
16c90 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 ^If the second
16ca0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
16cb0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
16cc0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 LOOKASIDE is not
16cd0 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 a multiple of 8
16ce0 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c , it is internal
16cf0 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f ly.** rounded do
16d00 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 wn to the next s
16d10 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 maller multiple
16d20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f of 8. ^(The loo
16d30 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a kaside memory.**
16d40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 configuration f
16d50 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f or a database co
16d60 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c nnection can onl
16d70 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 y be changed whe
16d80 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 n that.** connec
16d90 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 tion is not curr
16da0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b ently using look
16db0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 aside memory, or
16dc0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a in other words.
16dd0 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 ** when the "cur
16de0 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 rent value" retu
16df0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
16e00 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 te3_db_status](D
16e10 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ,[SQLITE_CONFIG_
16e20 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 LOOKASIDE],...)
16e30 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 is zero..** Any
16e40 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 attempt to chang
16e50 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 e the lookaside
16e60 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 memory configura
16e70 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 tion when lookas
16e80 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 ide.** memory is
16e90 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 in use leaves t
16ea0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e he configuration
16eb0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 unchanged and r
16ec0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 eturns .** [SQLI
16ed0 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e TE_BUSY].)^</dd>
16ee0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
16ef0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
16f00 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c E_FKEY</dt>.** <
16f10 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
16f20 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 is used to enab
16f30 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 le or disable th
16f40 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 e enforcement of
16f50 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 .** [foreign key
16f60 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 constraints].
16f70 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 There should be
16f80 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 two additional a
16f90 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 rguments..** The
16fa0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
16fb0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 is an integer wh
16fc0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 ich is 0 to disa
16fd0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 ble FK enforceme
16fe0 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 nt,.** positive
16ff0 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 to enable FK enf
17000 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 orcement or nega
17010 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b tive to leave FK
17020 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 enforcement.**
17030 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 unchanged. The
17040 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
17050 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
17060 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f an integer into
17070 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 which.** is wri
17080 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 tten 0 or 1 to i
17090 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 ndicate whether
170a0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 FK enforcement i
170b0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 s off or on.** f
170c0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 ollowing this ca
170d0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ll. The second
170e0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
170f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
17100 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 in.** which cas
17110 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 e the FK enforce
17120 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 ment setting is
17130 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 not reported bac
17140 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c k. </dd>.**.** <
17150 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
17160 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 IG_ENABLE_TRIGGE
17170 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e R</dt>.** <dd> ^
17180 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 This option is u
17190 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 sed to enable or
171a0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 disable [CREATE
171b0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 TRIGGER | trigg
171c0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 ers]..** There s
171d0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 hould be two add
171e0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
171f0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 s..** The first
17200 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 argument is an i
17210 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
17220 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 0 to disable tri
17230 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 ggers,.** positi
17240 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 ve to enable tri
17250 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 ggers or negativ
17260 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 e to leave the s
17270 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 etting unchanged
17280 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
17290 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
172a0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
172b0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a eger into which.
172c0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ** is written 0
172d0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
172e0 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 whether trigger
172f0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f s are disabled o
17300 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c r enabled.** fol
17310 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c lowing this call
17320 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
17330 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 rameter may be a
17340 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 NULL pointer, i
17350 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 n.** which case
17360 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 the trigger sett
17370 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 ing is not repor
17380 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a ted back. </dd>.
17390 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 **.** </dl>.*/.#
173a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
173b0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
173c0 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 1001 /*
173d0 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f void* int int */
173e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
173f0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
17400 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f FKEY 1002 /
17410 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 * int int* */.#d
17420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
17430 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 ONFIG_ENABLE_TRI
17440 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 GGER 1003 /* i
17450 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a nt int* */.../*.
17460 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 ** CAPI3REF: Ena
17470 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 ble Or Disable E
17480 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 xtended Result C
17490 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 odes.** METHOD:
174a0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
174b0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e he sqlite3_exten
174c0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
174d0 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c () routine enabl
174e0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
174f0 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 he.** [extended
17500 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 result codes] fe
17510 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e ature of SQLite.
17520 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 ^The extended r
17530 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 esult.** codes a
17540 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 re disabled by d
17550 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f efault for histo
17560 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c rical compatibil
17570 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ity..*/.SQLITE_A
17580 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
17590 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 DCALL sqlite3_ex
175a0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
175b0 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e des(sqlite3*, in
175c0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a t onoff);../*.**
175d0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 CAPI3REF: Last
175e0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 Insert Rowid.**
175f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
17600 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 **.** ^Each entr
17610 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 y in most SQLite
17620 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 tables (except
17630 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 for [WITHOUT ROW
17640 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 ID] tables).** h
17650 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 as a unique 64-b
17660 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 it signed.** int
17670 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 eger key called
17680 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f the [ROWID | "ro
17690 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 wid"]. ^The rowi
176a0 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 d is always avai
176b0 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 lable.** as an u
176c0 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e ndeclared column
176d0 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 named ROWID, OI
176e0 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 D, or _ROWID_ as
176f0 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a long as those.*
17700 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 * names are not
17710 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 also used by exp
17720 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 licitly declared
17730 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a columns. ^If.**
17740 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 the table has a
17750 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 column of type
17760 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 [INTEGER PRIMARY
17770 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 KEY] then that
17780 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f column.** is ano
17790 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 ther alias for t
177a0 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 he rowid..**.**
177b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 ^The sqlite3_las
177c0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 t_insert_rowid(D
177d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
177e0 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 rns the [rowid]
177f0 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 of the .** most
17800 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 recent successfu
17810 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 l [INSERT] into
17820 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 a rowid table or
17830 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d [virtual table]
17840 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 .** on database
17850 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a connection D..**
17860 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b ^Inserts into [
17870 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 WITHOUT ROWID] t
17880 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 ables are not re
17890 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e corded..** ^If n
178a0 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e o successful [IN
178b0 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 SERT]s into rowi
178c0 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 d tables.** have
178d0 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f ever occurred o
178e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
178f0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a onnection D, .**
17900 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 then sqlite3_la
17910 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
17920 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e D) returns zero.
17930 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b .**.** ^(If an [
17940 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 INSERT] occurs w
17950 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 ithin a trigger
17960 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 or within a [vir
17970 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d tual table].** m
17980 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 ethod, then this
17990 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 routine will re
179a0 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d turn the [rowid]
179b0 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 of the inserted
179c0 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 .** row as long
179d0 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f as the trigger o
179e0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 r virtual table
179f0 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e method is runnin
17a00 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 g..** But once t
17a10 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 he trigger or vi
17a20 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 rtual table meth
17a30 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c od ends, the val
17a40 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 ue returned .**
17a50 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 by this routine
17a60 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 reverts to what
17a70 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 it was before th
17a80 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 e trigger or vir
17a90 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 tual.** table me
17aa0 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a thod began.)^.**
17ab0 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d .** ^An [INSERT]
17ac0 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 that fails due
17ad0 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 to a constraint
17ae0 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 violation is not
17af0 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c a.** successful
17b00 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f [INSERT] and do
17b10 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
17b20 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
17b30 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 by this.** rout
17b40 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 ine. ^Thus INSE
17b50 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 RT OR FAIL, INSE
17b60 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e RT OR IGNORE, IN
17b70 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b SERT OR ROLLBACK
17b80 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 ,.** and INSERT
17b90 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f OR ABORT make no
17ba0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 changes to the
17bb0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
17bc0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 this.** routine
17bd0 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 when their inser
17be0 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 tion fails. ^(W
17bf0 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 hen INSERT OR RE
17c00 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 PLACE.** encount
17c10 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 ers a constraint
17c20 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 violation, it d
17c30 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 oes not fail. T
17c40 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e he.** INSERT con
17c50 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 tinues to comple
17c60 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 tion after delet
17c70 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 ing rows that ca
17c80 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 used.** the cons
17c90 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 traint problem s
17ca0 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c o INSERT OR REPL
17cb0 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 ACE will always
17cc0 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 change.** the re
17cd0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
17ce0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a is interface.)^.
17cf0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 **.** ^For the p
17d00 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 urposes of this
17d10 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 routine, an [INS
17d20 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 ERT] is consider
17d30 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 ed to.** be succ
17d40 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 essful even if i
17d50 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c t is subsequentl
17d60 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a y rolled back..*
17d70 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
17d80 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 on is accessible
17d90 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e to SQL statemen
17da0 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c ts via the.** [l
17db0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
17dc0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
17dd0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 ..**.** If a sep
17de0 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 arate thread per
17df0 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 forms a new [INS
17e00 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 ERT] on the same
17e10 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
17e20 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 nection while th
17e30 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f e [sqlite3_last_
17e40 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a insert_rowid()].
17e50 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ** function is r
17e60 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 unning and thus
17e70 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 changes the last
17e80 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c insert [rowid],
17e90 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c .** then the val
17ea0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b ue returned by [
17eb0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
17ec0 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a ert_rowid()] is.
17ed0 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 ** unpredictable
17ee0 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 and might not e
17ef0 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 qual either the
17f00 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a old or the new.*
17f10 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 * last insert [r
17f20 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 owid]..*/.SQLITE
17f30 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
17f40 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 64 SQLITE_STDCAL
17f50 4c 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 L sqlite3_last_i
17f60 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 nsert_rowid(sqli
17f70 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
17f80 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 PI3REF: Count Th
17f90 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 e Number Of Rows
17fa0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 Modified.** MET
17fb0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
17fc0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
17fd0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
17fe0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 mber of rows mod
17ff0 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 ified, inserted
18000 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 or.** deleted by
18010 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
18020 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 ly completed INS
18030 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 ERT, UPDATE or D
18040 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 ELETE.** stateme
18050 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 nt on the databa
18060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 se connection sp
18070 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f ecified by the o
18080 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a nly parameter..*
18090 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 * ^Executing any
180a0 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 other type of S
180b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 QL statement doe
180c0 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 s not modify the
180d0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
180e0 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 ed by this funct
180f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 ion..**.** ^Only
18100 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 changes made di
18110 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e rectly by the IN
18120 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 SERT, UPDATE or
18130 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
18140 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 are.** consider
18150 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 ed - auxiliary c
18160 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 hanges caused by
18170 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
18180 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a | triggers], .*
18190 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 * [foreign key a
181a0 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c ctions] or [REPL
181b0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 ACE] constraint
181c0 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e resolution are n
181d0 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a ot counted..** .
181e0 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 ** Changes to a
181f0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e view that are in
18200 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a tercepted by .**
18210 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 [INSTEAD OF tri
18220 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f gger | INSTEAD O
18230 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 F triggers] are
18240 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 not counted. ^Th
18250 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 e value .** retu
18260 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
18270 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 changes() immedi
18280 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 ately after an I
18290 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 NSERT, UPDATE or
182a0 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 .** DELETE stat
182b0 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 ement run on a v
182c0 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 iew is always ze
182d0 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 ro. Only changes
182e0 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a made to real .*
182f0 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 * tables are cou
18300 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e nted..**.** Thin
18310 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 gs are more comp
18320 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 licated if the s
18330 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
18340 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 function is.**
18350 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 executed while a
18360 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d trigger program
18370 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 is running. Thi
18380 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 s may happen if
18390 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 the.** program u
183a0 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 ses the [changes
183b0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
183c0 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 , or if some oth
183d0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 er callback.** f
183e0 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 unction invokes
183f0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
18400 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 ) directly. Esse
18410 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 ntially:.** .**
18420 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e <ul>.** <li> ^
18430 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 (Before entering
18440 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 a trigger progr
18450 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 am the value ret
18460 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 urned by.**
18470 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 sqlite3_chang
18480 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 es() function is
18490 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 saved. After th
184a0 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 e trigger progra
184b0 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 m .** has
184c0 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f finished, the o
184d0 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 riginal value is
184e0 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 restored.)^.**
184f0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 .** <li> ^(Wit
18500 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 hin a trigger pr
18510 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 ogram each INSER
18520 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 T, UPDATE and DE
18530 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 LETE .**
18540 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 statement sets t
18550 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
18560 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 d by sqlite3_cha
18570 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 nges() .**
18580 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f upon completio
18590 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 n as normal. Of
185a0 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c course, this val
185b0 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c ue will not incl
185c0 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 ude .** a
185d0 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f ny changes perfo
185e0 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 rmed by sub-trig
185f0 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c gers, as the sql
18600 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a ite3_changes() .
18610 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 ** value
18620 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e will be saved an
18630 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 d restored after
18640 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 each sub-trigge
18650 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 r has run.)^.**
18660 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 </ul>.** .** ^Th
18670 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 is means that if
18680 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 the changes() S
18690 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 QL function (or
186a0 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 similar) is used
186b0 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 .** by the first
186c0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 INSERT, UPDATE
186d0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d or DELETE statem
186e0 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 ent within a tri
186f0 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 gger, it .** ret
18700 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 urns the value a
18710 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 s set when the c
18720 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 alling statement
18730 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 began executing
18740 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 ..** ^If it is u
18750 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e sed by the secon
18760 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 d or subsequent
18770 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 such statement w
18780 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 ithin a trigger
18790 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 .** program, the
187a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
187b0 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d reflects the num
187c0 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 ber of rows modi
187d0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 fied by the .**
187e0 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c previous INSERT,
187f0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 UPDATE or DELET
18800 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 E statement with
18810 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 in the same trig
18820 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ger..**.** See a
18830 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
18840 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
18850 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 ] interface, the
18860 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 .** [count_chang
18870 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 es pragma], and
18880 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 the [changes() S
18890 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
188a0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
188b0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
188c0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
188d0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
188e0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
188f0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
18900 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
18910 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
18920 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 turned.** is unp
18930 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
18940 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
18950 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
18960 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
18970 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
18980 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
18990 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 * CAPI3REF: Tota
189a0 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 l Number Of Rows
189b0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 Modified.** MET
189c0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
189d0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
189e0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f n returns the to
189f0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f tal number of ro
18a00 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 ws inserted, mod
18a10 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 ified or.** dele
18a20 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 ted by all [INSE
18a30 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 RT], [UPDATE] or
18a40 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d [DELETE] statem
18a50 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a ents completed.*
18a60 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 * since the data
18a70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
18a80 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c was opened, incl
18a90 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 uding those exec
18aa0 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 uted as.** part
18ab0 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 of trigger progr
18ac0 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 ams. ^Executing
18ad0 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f any other type o
18ae0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a f SQL statement.
18af0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 ** does not affe
18b00 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ct the value ret
18b10 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
18b20 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
18b30 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 ..** .** ^Change
18b40 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f s made as part o
18b50 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 f [foreign key a
18b60 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c ctions] are incl
18b70 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 uded in the.** c
18b80 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 ount, but those
18b90 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 made as part of
18ba0 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 REPLACE constrai
18bb0 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 nt resolution ar
18bc0 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 e.** not. ^Chang
18bd0 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 es to a view tha
18be0 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 t are intercepte
18bf0 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 d by INSTEAD OF
18c00 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 triggers .** are
18c10 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a not counted..**
18c20 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 .** See also th
18c30 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 e [sqlite3_chang
18c40 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c es()] interface,
18c50 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 the.** [count_c
18c60 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 hanges pragma],
18c70 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 and the [total_c
18c80 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e hanges() SQL fun
18c90 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 ction]..**.** If
18ca0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
18cb0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 ad makes changes
18cc0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 on the same dat
18cd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18ce0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 .** while [sqlit
18cf0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
18d00 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
18d10 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a hen the value.**
18d20 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 returned is unp
18d30 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
18d40 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
18d50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
18d60 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
18d70 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
18d80 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b anges(sqlite3*);
18d90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
18da0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f : Interrupt A Lo
18db0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 ng-Running Query
18dc0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
18dd0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 te3.**.** ^This
18de0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 function causes
18df0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 any pending data
18e00 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 base operation t
18e10 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 o abort and.** r
18e20 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 eturn at its ear
18e30 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 liest opportunit
18e40 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 y. This routine
18e50 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 is typically.**
18e60 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e called in respon
18e70 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 se to a user act
18e80 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 ion such as pres
18e90 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a sing "Cancel".**
18ea0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 or Ctrl-C where
18eb0 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 the user wants
18ec0 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 a long query ope
18ed0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a ration to halt.*
18ee0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a * immediately..*
18ef0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 *.** ^It is safe
18f00 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f to call this ro
18f10 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 utine from a thr
18f20 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 ead different fr
18f30 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 om the.** thread
18f40 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 that is current
18f50 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 ly running the d
18f60 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f atabase operatio
18f70 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 n. But it.** is
18f80 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c not safe to cal
18f90 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 l this routine w
18fa0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
18fb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 connection] that
18fc0 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 .** is closed or
18fd0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 might close bef
18fe0 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 ore sqlite3_inte
18ff0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e rrupt() returns.
19000 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 .**.** ^If an SQ
19010 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 L operation is v
19020 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 ery nearly finis
19030 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 hed at the time
19040 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f when.** sqlite3_
19050 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 interrupt() is c
19060 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d alled, then it m
19070 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e ight not have an
19080 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 opportunity.**
19090 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 to be interrupte
190a0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 d and might cont
190b0 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 inue to completi
190c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 on..**.** ^An SQ
190d0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 L operation that
190e0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 is interrupted
190f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c will return [SQL
19100 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a ITE_INTERRUPT]..
19110 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 ** ^If the inter
19120 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 rupted SQL opera
19130 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 tion is an INSER
19140 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
19150 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 LETE.** that is
19160 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 inside an explic
19170 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 it transaction,
19180 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 then the entire
19190 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 transaction.** w
191a0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 ill be rolled ba
191b0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ck automatically
191c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
191d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 ite3_interrupt(D
191e0 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 ) call is in eff
191f0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 ect until all cu
19200 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a rrently running.
19210 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
19220 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 s on [database c
19230 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d onnection] D com
19240 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 plete. ^Any new
19250 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
19260 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
19270 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 ted after the sq
19280 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
19290 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 ) call and befor
192a0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e e the .** runnin
192b0 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 g statements rea
192c0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e ches zero are in
192d0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 terrupted as if
192e0 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a they had been.**
192f0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 running prior t
19300 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e o the sqlite3_in
19310 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 terrupt() call.
19320 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d ^New SQL statem
19330 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
19340 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
19350 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 he running state
19360 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 ment count reach
19370 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e es zero are.** n
19380 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 ot effected by t
19390 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
193a0 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 rupt()..** ^A ca
193b0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ll to sqlite3_in
193c0 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 terrupt(D) that
193d0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 occurs when ther
193e0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 e are no running
193f0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
19400 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e ts is a no-op an
19410 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 d has no effect
19420 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 on SQL statement
19430 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
19440 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 arted after the
19450 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
19460 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 t() call returns
19470 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 ..**.** If the d
19480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19490 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 on closes while
194a0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 [sqlite3_interru
194b0 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e pt()].** is runn
194c0 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 ing then bad thi
194d0 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 ngs will likely
194e0 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 happen..*/.SQLIT
194f0 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 E_API void SQLIT
19500 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
19510 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 3_interrupt(sqli
19520 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
19530 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e PI3REF: Determin
19540 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 e If An SQL Stat
19550 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 ement Is Complet
19560 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f e.**.** These ro
19570 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 utines are usefu
19580 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 l during command
19590 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 -line input to d
195a0 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a etermine if the.
195b0 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 ** currently ent
195c0 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 ered text seems
195d0 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 to form a comple
195e0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 te SQL statement
195f0 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 or.** if additi
19600 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 onal input is ne
19610 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 eded before send
19620 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 ing the text int
19630 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 o.** SQLite for
19640 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 parsing. ^These
19650 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
19660 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 1 if the input
19670 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 string.** appear
19680 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 s to be a comple
19690 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 te SQL statement
196a0 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 . ^A statement
196b0 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a is judged to be.
196c0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 ** complete if i
196d0 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 t ends with a se
196e0 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e micolon token an
196f0 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 d is not a prefi
19700 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 x of a.** well-f
19710 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 ormed CREATE TRI
19720 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 GGER statement.
19730 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 ^Semicolons tha
19740 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 t are embedded w
19750 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 ithin.** string
19760 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 literals or quot
19770 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 ed identifier na
19780 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 mes or comments
19790 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 are not.** indep
197a0 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 endent tokens (t
197b0 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 hey are part of
197c0 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 the token in whi
197d0 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 ch they are.** e
197e0 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 mbedded) and thu
197f0 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 s do not count a
19800 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 s a statement te
19810 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 rminator. ^Whit
19820 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f espace.** and co
19830 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c mments that foll
19840 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d ow the final sem
19850 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 icolon are ignor
19860 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 ed..**.** ^These
19870 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
19880 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 0 if the statem
19890 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 ent is incomplet
198a0 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d e. ^If a.** mem
198b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
198c0 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 ails, then SQLIT
198d0 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 E_NOMEM is retur
198e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ned..**.** ^Thes
198f0 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f e routines do no
19900 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 t parse the SQL
19910 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a statements thus.
19920 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 ** will not dete
19930 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 ct syntactically
19940 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a incorrect SQL..
19950 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 **.** ^(If SQLit
19960 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 e has not been i
19970 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 nitialized using
19980 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
19990 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a lize()] prior .*
199a0 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 * to invoking sq
199b0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
199c0 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f () then sqlite3_
199d0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
199e0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d invoked.** autom
199f0 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 atically by sqli
19a00 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
19a10 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 . If that initi
19a20 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c alization fails,
19a30 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 .** then the ret
19a40 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 urn value from s
19a50 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
19a60 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 6() will be non-
19a70 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 zero.** regardle
19a80 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
19a90 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 not the input S
19aa0 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 QL is complete.)
19ab0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 ^.**.** The inpu
19ac0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
19ad0 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 mplete()] must b
19ae0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 e a zero-termina
19af0 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 ted.** UTF-8 str
19b00 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ing..**.** The i
19b10 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 nput to [sqlite3
19b20 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d _complete16()] m
19b30 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 ust be a zero-te
19b40 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d rminated.** UTF-
19b50 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 16 string in nat
19b60 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a ive byte order..
19b70 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
19b80 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
19b90 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
19ba0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 e(const char *sq
19bb0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 l);.SQLITE_API i
19bc0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
19bd0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 L sqlite3_comple
19be0 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 te16(const void
19bf0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 *sql);../*.** CA
19c00 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 PI3REF: Register
19c10 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 A Callback To H
19c20 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 andle SQLITE_BUS
19c30 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 Y Errors.** KEYW
19c40 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 ORDS: {busy-hand
19c50 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 ler callback} {b
19c60 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 usy handler}.**
19c70 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
19c80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
19c90 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
19ca0 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 D,X,P) routine s
19cb0 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ets a callback f
19cc0 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 unction X.** tha
19cd0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b t might be invok
19ce0 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 ed with argument
19cf0 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 P whenever.** a
19d00 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 n attempt is mad
19d10 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 e to access a da
19d20 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 tabase table ass
19d30 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 ociated with.**
19d40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
19d50 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f tion] D when ano
19d60 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f ther thread.** o
19d70 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 r process has th
19d80 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a e table locked..
19d90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 ** The sqlite3_b
19da0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e usy_handler() in
19db0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
19dc0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 to implement.**
19dd0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 [sqlite3_busy_ti
19de0 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 meout()] and [PR
19df0 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 AGMA busy_timeou
19e00 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 t]..**.** ^If th
19e10 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 e busy callback
19e20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 is NULL, then [S
19e30 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 QLITE_BUSY].** i
19e40 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 s returned immed
19e50 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f iately upon enco
19e60 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 untering the loc
19e70 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 k. ^If the busy
19e80 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
19e90 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 not NULL, then t
19ea0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 he callback migh
19eb0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 t be invoked wit
19ec0 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e h two arguments.
19ed0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
19ee0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
19ef0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 e busy handler i
19f00 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
19f10 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 void* pointer wh
19f20 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 ich.** is the th
19f30 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ird argument to
19f40 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
19f50 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 dler(). ^The se
19f60 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
19f70 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e .** the busy han
19f80 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 dler callback is
19f90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 the number of t
19fa0 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 imes that the bu
19fb0 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a sy handler has.*
19fc0 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 * been invoked p
19fd0 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 reviously for th
19fe0 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 e same locking e
19ff0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a vent. ^If the.*
1a000 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 * busy callback
1a010 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 returns 0, then
1a020 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 no additional at
1a030 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 tempts are made
1a040 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 to.** access the
1a050 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 database and [S
1a060 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 QLITE_BUSY] is r
1a070 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 eturned.** to th
1a080 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a e application..*
1a090 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 * ^If the callba
1a0a0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
1a0b0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 ero, then anothe
1a0c0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 r attempt.** is
1a0d0 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 made to access t
1a0e0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 he database and
1a0f0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 the cycle repeat
1a100 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 s..**.** The pre
1a110 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 sence of a busy
1a120 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 handler does not
1a130 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 guarantee that
1a140 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b it will be invok
1a150 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 ed.** when there
1a160 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 is lock content
1a170 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 ion. ^If SQLite
1a180 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 determines that
1a190 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 invoking the bus
1a1a0 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 y.** handler cou
1a1b0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 ld result in a d
1a1c0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c eadlock, it will
1a1d0 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 go ahead and re
1a1e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 turn [SQLITE_BUS
1a1f0 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 Y].** to the app
1a200 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 lication instead
1a210 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 of invoking the
1a220 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 .** busy handle
1a230 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 r..** Consider a
1a240 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 scenario where
1a250 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 one process is h
1a260 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f olding a read lo
1a270 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 ck that.** it is
1a280 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f trying to promo
1a290 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 te to a reserved
1a2a0 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 lock and.** a s
1a2b0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 econd process is
1a2c0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 holding a reser
1a2d0 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 ved lock that it
1a2e0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f is trying.** to
1a2f0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 promote to an e
1a300 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 xclusive lock.
1a310 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 The first proces
1a320 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 s cannot proceed
1a330 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 .** because it i
1a340 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 s blocked by the
1a350 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 second and the
1a360 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 second process c
1a370 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 annot.** proceed
1a380 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 because it is b
1a390 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 locked by the fi
1a3a0 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 rst. If both pr
1a3b0 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b ocesses.** invok
1a3c0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c e the busy handl
1a3d0 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c ers, neither wil
1a3e0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 l make any progr
1a3f0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c ess. Therefore,
1a400 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 .** SQLite retur
1a410 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ns [SQLITE_BUSY]
1a420 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 for the first p
1a430 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 rocess, hoping t
1a440 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c hat this.** will
1a450 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 induce the firs
1a460 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c t process to rel
1a470 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f ease its read lo
1a480 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 ck and allow.**
1a490 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 the second proce
1a4a0 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a ss to proceed..*
1a4b0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c *.** ^The defaul
1a4c0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 t busy callback
1a4d0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e is NULL..**.** ^
1a4e0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 (There can only
1a4f0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 be a single busy
1a500 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 handler defined
1a510 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 for each.** [da
1a520 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1a530 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e n]. Setting a n
1a540 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 ew busy handler
1a550 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 clears any.** pr
1a560 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e eviously set han
1a570 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 dler.)^ ^Note t
1a580 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c hat calling [sql
1a590 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
1a5a0 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 t()].** or evalu
1a5b0 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 ating [PRAGMA bu
1a5c0 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 sy_timeout=N] wi
1a5d0 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a ll change the.**
1a5e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e busy handler an
1a5f0 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 d thus clear any
1a600 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 previously set
1a610 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a busy handler..**
1a620 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c .** The busy cal
1a630 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 lback should not
1a640 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e take any action
1a650 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 s which modify t
1a660 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 he.** database c
1a670 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
1a680 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 nvoked the busy
1a690 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 handler. In oth
1a6a0 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 er words,.** the
1a6b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
1a6c0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 not reentrant.
1a6d0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e Any such action
1a6e0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 s.** result in u
1a6f0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f ndefined behavio
1a700 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 r..** .** A busy
1a710 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f handler must no
1a720 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 t close the data
1a730 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
1a740 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 ** or [prepared
1a750 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
1a760 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 invoked the busy
1a770 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c handler..*/.SQL
1a780 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
1a790 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
1a7a0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
1a7b0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 sqlite3*, int(*)
1a7c0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 (void*,int), voi
1a7d0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
1a7e0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 3REF: Set A Busy
1a7f0 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 Timeout.** METH
1a800 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
1a810 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
1a820 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f sets a [sqlite3_
1a830 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 busy_handler | b
1a840 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 usy handler] tha
1a850 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 t sleeps.** for
1a860 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 a specified amou
1a870 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 nt of time when
1a880 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 a table is locke
1a890 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 d. ^The handler
1a8a0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d .** will sleep m
1a8b0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e ultiple times un
1a8c0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 til at least "ms
1a8d0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f " milliseconds o
1a8e0 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 f sleeping.** ha
1a8f0 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 ve accumulated.
1a900 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 ^After at least
1a910 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
1a920 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a ds of sleeping,.
1a930 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 ** the handler r
1a940 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 eturns 0 which c
1a950 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 auses [sqlite3_s
1a960 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e tep()] to return
1a970 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
1a980 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e ]..**.** ^Callin
1a990 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 g this routine w
1a9a0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 ith an argument
1a9b0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 less than or equ
1a9c0 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 al to zero.** tu
1a9d0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 rns off all busy
1a9e0 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a handlers..**.**
1a9f0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ^(There can onl
1aa00 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
1aa10 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 sy handler for a
1aa20 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b particular.** [
1aa30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1aa40 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 ion] at any give
1aa50 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e n moment. If an
1aa60 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c other busy handl
1aa70 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 er.** was define
1aa80 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 d (using [sqlit
1aa90 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
1aaa0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c )]) prior to cal
1aab0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 ling.** this rou
1aac0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 tine, that other
1aad0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
1aae0 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a cleared.)^.**.*
1aaf0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 * See also: [PR
1ab00 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 AGMA busy_timeou
1ab10 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 t].*/.SQLITE_API
1ab20 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
1ab30 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79 ALL sqlite3_busy
1ab40 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 _timeout(sqlite3
1ab50 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a *, int ms);../*.
1ab60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
1ab70 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 venience Routine
1ab80 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 s For Running Qu
1ab90 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a eries.** METHOD:
1aba0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 sqlite3.**.** T
1abb0 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 his is a legacy
1abc0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 interface that i
1abd0 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 s preserved for
1abe0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
1abf0 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 ibility..** Use
1ac00 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 of this interfac
1ac10 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 e is not recomme
1ac20 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 nded..**.** Defi
1ac30 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 nition: A <b>res
1ac40 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 ult table</b> is
1ac50 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 memory data str
1ac60 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 ucture created b
1ac70 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 y the.** [sqlite
1ac80 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 3_get_table()] i
1ac90 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 nterface. A res
1aca0 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 ult table record
1acb0 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 s the.** complet
1acc0 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 e query results
1acd0 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 from one or more
1ace0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 queries..**.**
1acf0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 The table concep
1ad00 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d tually has a num
1ad10 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 ber of rows and
1ad20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a columns. But.**
1ad30 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 these numbers a
1ad40 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 re not part of t
1ad50 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
1ad60 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a itself. These.*
1ad70 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 * numbers are ob
1ad80 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c tained separatel
1ad90 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 y. Let N be the
1ada0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a number of rows.
1adb0 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 ** and M be the
1adc0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
1add0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c s..**.** A resul
1ade0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 t table is an ar
1adf0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
1ae00 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 to zero-terminat
1ae10 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 ed UTF-8 strings
1ae20 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 ..** There are (
1ae30 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 N+1)*M elements
1ae40 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 in the array. T
1ae50 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 he first M point
1ae60 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 ers point.** to
1ae70 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1ae80 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f strings that co
1ae90 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 ntain the names
1aea0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a of the columns..
1aeb0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 ** The remaining
1aec0 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 entries all poi
1aed0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 nt to query resu
1aee0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 lts. NULL value
1aef0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e s result.** in N
1af00 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 ULL pointers. A
1af10 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 ll other values
1af20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 are in their UTF
1af30 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 -8 zero-terminat
1af40 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 ed.** string rep
1af50 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 resentation as r
1af60 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
1af70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
1af80 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 )]..**.** A resu
1af90 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 lt table might c
1afa0 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 onsist of one or
1afb0 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c more memory all
1afc0 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 ocations..** It
1afd0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 is not safe to p
1afe0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 ass a result tab
1aff0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b le directly to [
1b000 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e sqlite3_free()].
1b010 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 .** A result tab
1b020 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 le should be dea
1b030 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b llocated using [
1b040 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
1b050 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 le()]..**.** ^(A
1b060 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 s an example of
1b070 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
1b080 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 format, suppose
1b090 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a a query result.
1b0a0 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 ** is as follows
1b0b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
1b0c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 ote><pre>.**
1b0d0 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 Name
1b0e0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 | Age.**
1b0f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1b100 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 -------.**
1b110 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 Alice |
1b120 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 43.** Bob
1b130 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a | 28.**
1b140 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 Cindy
1b150 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 | 21.** </pr
1b160 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1b170 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 **.** There are
1b180 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 two column (M==2
1b190 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 ) and three rows
1b1a0 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 (N==3). Thus t
1b1b0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 he.** result tab
1b1c0 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 le has 8 entries
1b1d0 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 . Suppose the r
1b1e0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 esult table is s
1b1f0 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 tored.** in an a
1b200 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 rray names azRes
1b210 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 ult. Then azRes
1b220 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 ult holds this c
1b230 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ontent:.**.** <b
1b240 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1b250 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1b260 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d lt[0] = "Nam
1b270 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
1b280 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 Result[1] =
1b290 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 "Age";.**
1b2a0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d azResult[2]
1b2b0 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 = "Alice";.**
1b2c0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1b2d0 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 91;3] = "43";.**
1b2e0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1b2f0 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b [4] = "Bob";
1b300 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1b310 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 ult[5] = "28
1b320 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1b330 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 esult[6] = "
1b340 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 Cindy";.**
1b350 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 azResult[7
1b360 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 ] = "21";.** </p
1b370 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1b380 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 )^.**.** ^The sq
1b390 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1b3a0 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 ) function evalu
1b3b0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 ates one or more
1b3c0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 .** semicolon-se
1b3d0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 parated SQL stat
1b3e0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 ements in the ze
1b3f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
1b400 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 F-8.** string of
1b410 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 its 2nd paramet
1b420 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 er and returns a
1b430 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f result table to
1b440 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 the.** pointer
1b450 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 given in its 3rd
1b460 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
1b470 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c * After the appl
1b480 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 ication has fini
1b490 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 shed with the re
1b4a0 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 sult from sqlite
1b4b0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 3_get_table(),.*
1b4c0 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 * it must pass t
1b4d0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
1b4e0 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 pointer to sqlit
1b4f0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 e3_free_table()
1b500 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 in order to.** r
1b510 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 elease the memor
1b520 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f y that was mallo
1b530 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 ced. Because of
1b540 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 the way the.**
1b550 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1b560 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 )] happens withi
1b570 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 n sqlite3_get_ta
1b580 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 ble(), the calli
1b590 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d ng.** function m
1b5a0 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 ust not try to c
1b5b0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 all [sqlite3_fre
1b5c0 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 e()] directly.
1b5d0 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 Only.** [sqlite3
1b5e0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 _free_table()] i
1b5f0 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 s able to releas
1b600 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f e the memory pro
1b610 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 perly and safely
1b620 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
1b630 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
1b640 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 interface is imp
1b650 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 lemented as a wr
1b660 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 apper around.**
1b670 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
1b680 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 . The sqlite3_g
1b690 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 et_table() routi
1b6a0 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 ne does not have
1b6b0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e access.** to an
1b6c0 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 y internal data
1b6d0 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 structures of SQ
1b6e0 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f Lite. It uses o
1b6f0 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a nly the public.*
1b700 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 * interface defi
1b710 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 ned here. As a
1b720 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 consequence, err
1b730 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 ors that occur i
1b740 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 n the.** wrapper
1b750 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f layer outside o
1b760 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b f the internal [
1b770 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
1b780 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 call are not.**
1b790 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 reflected in sub
1b7a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
1b7b0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
1b7c0 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 e()] or.** [sqli
1b7d0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a te3_errmsg()]..*
1b7e0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
1b7f0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
1b800 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
1b810 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 e(. sqlite3 *db
1b820 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e , /* An
1b830 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a open database *
1b840 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
1b850 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c zSql, /* SQL
1b860 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 to be evaluated
1b870 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 */. char ***pa
1b880 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 zResult, /* R
1b890 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 esults of the qu
1b8a0 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e ery */. int *pn
1b8b0 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f Row, /
1b8c0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 * Number of resu
1b8d0 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 lt rows written
1b8e0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 here */. int *p
1b8f0 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 nColumn,
1b900 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 /* Number of res
1b910 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 ult columns writ
1b920 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 ten here */. ch
1b930 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 ar **pzErrmsg
1b940 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 /* Error msg
1b950 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
1b960 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .);.SQLITE_API v
1b970 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 oid SQLITE_STDCA
1b980 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f LL sqlite3_free_
1b990 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 table(char **res
1b9a0 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ult);../*.** CAP
1b9b0 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 I3REF: Formatted
1b9c0 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 String Printing
1b9d0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a Functions.**.**
1b9e0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1b9f0 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 are work-alikes
1ba00 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 of the "printf()
1ba10 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 " family of func
1ba20 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 tions.** from th
1ba30 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
1ba40 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 rary..** These r
1ba50 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 outines understa
1ba60 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 nd most of the c
1ba70 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 ommon K&R format
1ba80 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a ting options,.**
1ba90 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 plus some addit
1baa0 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 ional non-standa
1bab0 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 rd formats, deta
1bac0 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e iled below..** N
1bad0 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 ote that some of
1bae0 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 the more obscur
1baf0 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 e formatting opt
1bb00 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 ions from recent
1bb10 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 .** C-library st
1bb20 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 andards are omit
1bb30 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d ted from this im
1bb40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a plementation..**
1bb50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1bb60 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 _mprintf() and s
1bb70 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
1bb80 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 ) routines write
1bb90 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 their.** result
1bba0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 s into memory ob
1bbb0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
1bbc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a ite3_malloc()]..
1bbd0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 ** The strings r
1bbe0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
1bbf0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 two routines sh
1bc00 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 ould be.** relea
1bc10 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
1bc20 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 free()]. ^Both
1bc30 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
1bc40 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
1bc50 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
1bc60 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
1bc70 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
1bc80 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
1bc90 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
1bca0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
1bcb0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
1bcc0 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 _snprintf() rout
1bcd0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ine is similar t
1bce0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 o "snprintf()" f
1bcf0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 rom.** the stand
1bd00 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 ard C library.
1bd10 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 The result is wr
1bd20 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a itten into the.*
1bd30 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 * buffer supplie
1bd40 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
1bd50 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 parameter whose
1bd60 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 size is given by
1bd70 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 .** the first pa
1bd80 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 rameter. Note th
1bd90 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 at the order of
1bda0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f the.** first two
1bdb0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 parameters is r
1bdc0 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 eversed from snp
1bdd0 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 rintf().)^ This
1bde0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 is an.** histor
1bdf0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 ical accident th
1be00 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 at cannot be fix
1be10 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ed without break
1be20 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 ing.** backwards
1be30 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 compatibility.
1be40 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 ^(Note also tha
1be50 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e t sqlite3_snprin
1be60 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 tf().** returns
1be70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 a pointer to its
1be80 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 buffer instead
1be90 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 of the number of
1bea0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 .** characters a
1beb0 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 ctually written
1bec0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e into the buffer.
1bed0 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 )^ We admit tha
1bee0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 t.** the number
1bef0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 of characters wr
1bf00 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 itten would be a
1bf10 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 more useful ret
1bf20 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 urn.** value but
1bf30 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 we cannot chang
1bf40 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 e the implementa
1bf50 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
1bf60 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f snprintf().** no
1bf70 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 w without breaki
1bf80 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ng compatibility
1bf90 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 ..**.** ^As long
1bfa0 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 as the buffer s
1bfb0 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 ize is greater t
1bfc0 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 han zero, sqlite
1bfd0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
1bfe0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 guarantees that
1bff0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c the buffer is al
1c000 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e ways zero-termin
1c010 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 ated. ^The firs
1c020 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 t.** parameter "
1c030 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 n" is the total
1c040 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 size of the buff
1c050 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 er, including sp
1c060 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a ace for.** the z
1c070 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero terminator.
1c080 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 So the longest
1c090 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 string that can
1c0a0 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a be completely.**
1c0b0 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 written will be
1c0c0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e n-1 characters.
1c0d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1c0e0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 te3_vsnprintf()
1c0f0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 routine is a var
1c100 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 args version of
1c110 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1c120 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ()..**.** These
1c130 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 routines all imp
1c140 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 lement some addi
1c150 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e tional formattin
1c160 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 g.** options tha
1c170 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 t are useful for
1c180 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 constructing SQ
1c190 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
1c1a0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 All of the usua
1c1b0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 l printf() forma
1c1c0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 tting options ap
1c1d0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f ply. In additio
1c1e0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 n, there.** is a
1c1f0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 re "%q", "%Q", "
1c200 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 %w" and "%z" opt
1c210 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ions..**.** ^(Th
1c220 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b e %q option work
1c230 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 s like %s in tha
1c240 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 t it substitutes
1c250 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 a nul-terminate
1c260 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d d.** string from
1c270 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 the argument li
1c280 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f st. But %q also
1c290 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 doubles every '
1c2a0 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a \'' character..*
1c2b0 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 * %q is designed
1c2c0 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 for use inside
1c2d0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c a string literal
1c2e0 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 .)^ By doubling
1c2f0 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 each '\''.** ch
1c300 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 aracter it escap
1c310 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 es that characte
1c320 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 r and allows it
1c330 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 to be inserted i
1c340 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e nto.** the strin
1c350 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 g..**.** For exa
1c360 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 mple, assume the
1c370 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 string variable
1c380 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 zText contains
1c390 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a text as follows:
1c3a0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1c3b0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 te><pre>.** cha
1c3c0 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 r *zText = "It's
1c3d0 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a a happy day!";.
1c3e0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1c3f0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 quote>.**.** One
1c400 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 can use this te
1c410 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 xt in an SQL sta
1c420 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 tement as follow
1c430 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
1c440 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
1c450 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
1c460 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
1c470 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
1c480 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 ALUES('%q')", zT
1c490 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 ext);.** sqlite
1c4a0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 3_exec(db, zSQL,
1c4b0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 0, 0, 0);.** s
1c4c0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c qlite3_free(zSQL
1c4d0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
1c4e0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
1c4f0 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 Because the %q f
1c500 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 ormat string is
1c510 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 used, the '\'' c
1c520 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 haracter in zTex
1c530 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 t.** is escaped
1c540 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 and the SQL gene
1c550 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c rated is as foll
1c560 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
1c570 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
1c580 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 INSERT INTO tab
1c590 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 le1 VALUES('It''
1c5a0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 s a happy day!')
1c5b0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1c5c0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
1c5d0 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 is is correct.
1c5e0 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 Had we used %s i
1c5f0 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 nstead of %q, th
1c600 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a e generated SQL.
1c610 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f ** would have lo
1c620 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a oked like this:.
1c630 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1c640 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 e><pre>.** INSE
1c650 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 RT INTO table1 V
1c660 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 ALUES('It's a ha
1c670 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c ppy day!');.** <
1c680 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1c690 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 e>.**.** This se
1c6a0 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 cond example is
1c6b0 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 an SQL syntax er
1c6c0 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 ror. As a gener
1c6d0 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 al rule you shou
1c6e0 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 ld.** always use
1c6f0 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 %q instead of %
1c700 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 s when inserting
1c710 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 text into a str
1c720 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a ing literal..**.
1c730 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 ** ^(The %Q opti
1c740 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 on works like %q
1c750 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 except it also
1c760 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 adds single quot
1c770 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 es around.** the
1c780 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 outside of the
1c790 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 total string. A
1c7a0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 dditionally, if
1c7b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e the parameter in
1c7c0 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 the.** argument
1c7d0 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 list is a NULL
1c7e0 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 pointer, %Q subs
1c7f0 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 titutes the text
1c800 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 "NULL" (without
1c810 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 .** single quote
1c820 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 s).)^ So, for e
1c830 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c xample, one coul
1c840 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c d say:.**.** <bl
1c850 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1c860 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 * char *zSQL =
1c870 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1c880 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 "INSERT INTO tab
1c890 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 le VALUES(%Q)",
1c8a0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 zText);.** sqli
1c8b0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 te3_exec(db, zSQ
1c8c0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 L, 0, 0, 0);.**
1c8d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 sqlite3_free(zS
1c8e0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f QL);.** </pre></
1c8f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
1c900 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 * The code above
1c910 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 will render a c
1c920 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 orrect SQL state
1c930 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c ment in the zSQL
1c940 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 .** variable eve
1c950 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 n if the zText v
1c960 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c ariable is a NUL
1c970 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
1c980 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d ^(The "%w" form
1c990 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 atting option is
1c9a0 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 like "%q" excep
1c9b0 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 t that it expect
1c9c0 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 s to.** be conta
1c9d0 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 ined within doub
1c9e0 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 le-quotes instea
1c9f0 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 d of single quot
1ca00 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 es, and it.** es
1ca10 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 capes the double
1ca20 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 -quote character
1ca30 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
1ca40 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 single-quote.**
1ca50 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 character.)^ Th
1ca60 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e e "%w" formattin
1ca70 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 g option is inte
1ca80 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 nded for safely
1ca90 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 inserting.** tab
1caa0 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 le and column na
1cab0 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 mes into a const
1cac0 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 ructed SQL state
1cad0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ment..**.** ^(Th
1cae0 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e e "%z" formattin
1caf0 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c g option works l
1cb00 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 ike "%s" but wit
1cb10 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f h the.** additio
1cb20 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 n that after the
1cb30 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e string has been
1cb40 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 read and copied
1cb50 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 into.** the res
1cb60 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 ult, [sqlite3_fr
1cb70 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 ee()] is called
1cb80 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 on the input str
1cb90 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 ing.)^.*/.SQLITE
1cba0 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 _API char *SQLIT
1cbb0 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f E_CDECL sqlite3_
1cbc0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
1cbd0 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 ar*,...);.SQLITE
1cbe0 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 _API char *SQLIT
1cbf0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
1cc00 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 3_vmprintf(const
1cc10 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 char*, va_list)
1cc20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 ;.SQLITE_API cha
1cc30 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 r *SQLITE_CDECL
1cc40 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1cc50 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 (int,char*,const
1cc60 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 char*, ...);.SQ
1cc70 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 LITE_API char *S
1cc80 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
1cc90 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 lite3_vsnprintf(
1cca0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 int,char*,const
1ccb0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b char*, va_list);
1ccc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1ccd0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
1cce0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a ion Subsystem.**
1ccf0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
1cd00 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 ore uses these t
1cd10 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hree routines fo
1cd20 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e r all of its own
1cd30 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d .** internal mem
1cd40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
1cd50 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 eeds. "Core" in
1cd60 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e the previous sen
1cd70 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f tence.** does no
1cd80 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 t include operat
1cd90 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
1cda0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e fic VFS implemen
1cdb0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 tation. The.**
1cdc0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 Windows VFS uses
1cdd0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 native malloc()
1cde0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 and free() for
1cdf0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e some operations.
1ce00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1ce10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 te3_malloc() rou
1ce20 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
1ce30 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 ointer to a bloc
1ce40 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 k.** of memory a
1ce50 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
1ce60 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 in length, where
1ce70 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 N is the parame
1ce80 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ter..** ^If sqli
1ce90 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 te3_malloc() is
1cea0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e unable to obtain
1ceb0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 sufficient free
1cec0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 .** memory, it r
1ced0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
1cee0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 inter. ^If the
1cef0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a parameter N to.*
1cf00 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
1cf10 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 () is zero or ne
1cf20 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 gative then sqli
1cf30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 te3_malloc() ret
1cf40 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 urns.** a NULL p
1cf50 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ointer..**.** ^T
1cf60 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f he sqlite3_mallo
1cf70 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 c64(N) routine w
1cf80 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a orks just like.*
1cf90 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
1cfa0 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 (N) except that
1cfb0 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 N is an unsigned
1cfc0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
1cfd0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 instead.** of a
1cfe0 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e signed 32-bit in
1cff0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 teger..**.** ^Ca
1d000 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 lling sqlite3_fr
1d010 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e ee() with a poin
1d020 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 ter previously r
1d030 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 eturned.** by sq
1d040 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f lite3_malloc() o
1d050 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
1d060 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 c() releases tha
1d070 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 t memory so.** t
1d080 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 hat it might be
1d090 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 reused. ^The sq
1d0a0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 lite3_free() rou
1d0b0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d tine is.** a no-
1d0c0 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 op if is called
1d0d0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
1d0e0 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 ter. Passing a
1d0f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
1d100 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 to sqlite3_free(
1d110 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 ) is harmless.
1d120 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 After being free
1d130 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f d, memory.** sho
1d140 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 uld neither be r
1d150 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e ead nor written.
1d160 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 Even reading p
1d170 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a reviously freed.
1d180 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 ** memory might
1d190 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d result in a segm
1d1a0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f entation fault o
1d1b0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 r other severe e
1d1c0 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 rror..** Memory
1d1d0 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 corruption, a se
1d1e0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 gmentation fault
1d1f0 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 , or other sever
1d200 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 e error.** might
1d210 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 result if sqlit
1d220 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c e3_free() is cal
1d230 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e led with a non-N
1d240 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ULL pointer that
1d250 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 .** was not obta
1d260 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
1d270 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 3_malloc() or sq
1d280 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e lite3_realloc().
1d290 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1d2a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1d2b0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
1d2c0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a pts to resize a.
1d2d0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 ** prior memory
1d2e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 allocation X to
1d2f0 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 be at least N by
1d300 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 tes..** ^If the
1d310 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 X parameter to s
1d320 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
1d330 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c ,N).** is a NULL
1d340 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 pointer then it
1d350 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 s behavior is id
1d360 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 entical to calli
1d370 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 ng.** sqlite3_ma
1d380 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 lloc(N)..** ^If
1d390 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 the N parameter
1d3a0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
1d3b0 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 oc(X,N) is zero
1d3c0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 or.** negative t
1d3d0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
1d3e0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 is exactly the
1d3f0 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a same as calling.
1d400 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 ** sqlite3_free(
1d410 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f X)..** ^sqlite3_
1d420 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 realloc(X,N) ret
1d430 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
1d440 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 o a memory alloc
1d450 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c ation.** of at l
1d460 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 east N bytes in
1d470 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 size or NULL if
1d480 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d insufficient mem
1d490 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 ory is available
1d4a0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 ..** ^If M is th
1d4b0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 e size of the pr
1d4c0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 ior allocation,
1d4d0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 then min(N,M) by
1d4e0 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 tes.** of the pr
1d4f0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 ior allocation a
1d500 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 re copied into t
1d510 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
1d520 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a buffer returned.
1d530 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 ** by sqlite3_re
1d540 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 alloc(X,N) and t
1d550 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
1d560 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a ion is freed..**
1d570 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 ^If sqlite3_rea
1d580 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e lloc(X,N) return
1d590 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 s NULL and N is
1d5a0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 positive, then t
1d5b0 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f he.** prior allo
1d5c0 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 cation is not fr
1d5d0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 eed..**.** ^The
1d5e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 sqlite3_realloc6
1d5f0 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 4(X,N) interface
1d600 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 s works the same
1d610 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 as.** sqlite3_r
1d620 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 ealloc(X,N) exce
1d630 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 pt that N is a 6
1d640 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 4-bit unsigned i
1d650 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a nteger instead.*
1d660 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 * of a 32-bit si
1d670 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a gned integer..**
1d680 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d .** ^If X is a m
1d690 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1d6a0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 previously obta
1d6b0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
1d6c0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 3_malloc(),.** s
1d6d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 qlite3_malloc64(
1d6e0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c ), sqlite3_reall
1d6f0 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 oc(), or sqlite3
1d700 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 _realloc64(), th
1d710 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 en.** sqlite3_ms
1d720 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 ize(X) returns t
1d730 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 he size of that
1d740 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1d750 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e n in bytes..** ^
1d760 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e The value return
1d770 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 ed by sqlite3_ms
1d780 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 ize(X) might be
1d790 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 larger than the
1d7a0 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 number.** of byt
1d7b0 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 es requested whe
1d7c0 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 n X was allocate
1d7d0 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e d. ^If X is a N
1d7e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
1d7f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a .** sqlite3_msiz
1d800 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 e(X) returns zer
1d810 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 o. If X points
1d820 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 to something tha
1d830 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 t is not.** the
1d840 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d beginning of mem
1d850 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 ory allocation,
1d860 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 or if it points
1d870 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a to a formerly.**
1d880 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c valid memory al
1d890 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 location that ha
1d8a0 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 s now been freed
1d8b0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
1d8c0 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 ior.** of sqlite
1d8d0 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 3_msize(X) is un
1d8e0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 defined and poss
1d8f0 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a ibly harmful..**
1d900 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 .** ^The memory
1d910 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
1d920 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 te3_malloc(), sq
1d930 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c lite3_realloc(),
1d940 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c .** sqlite3_mall
1d950 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 oc64(), and sqli
1d960 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a te3_realloc64().
1d970 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 ** is always ali
1d980 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 gned to at least
1d990 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 an 8 byte bound
1d9a0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 ary, or to a.**
1d9b0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 4 byte boundary
1d9c0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 if the [SQLITE_4
1d9d0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 _BYTE_ALIGNED_MA
1d9e0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 LLOC] compile-ti
1d9f0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 me.** option is
1da00 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 used..**.** In S
1da10 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
1da20 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 5.0 and 3.5.1, i
1da30 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 t was possible t
1da40 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 o define.** the
1da50 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f SQLITE_OMIT_MEMO
1da60 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 RY_ALLOCATION wh
1da70 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 ich would cause
1da80 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 the built-in.**
1da90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
1daa0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
1dab0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 to be omitted.
1dac0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 That capability
1dad0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 .** is no longer
1dae0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 provided. Only
1daf0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
1db00 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 allocators can
1db10 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 be used..**.** P
1db20 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 rior to SQLite v
1db30 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 ersion 3.7.10, t
1db40 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e he Windows OS in
1db50 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 terface layer ca
1db60 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 lled.** the syst
1db70 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 em malloc() and
1db80 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 free() directly
1db90 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a when converting.
1dba0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 ** filenames bet
1dbb0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 ween the UTF-8 e
1dbc0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 ncoding used by
1dbd0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 SQLite.** and wh
1dbe0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 atever filename
1dbf0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 encoding is used
1dc00 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c by the particul
1dc10 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e ar Windows.** in
1dc20 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d stallation. Mem
1dc30 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
1dc40 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 rrors were detec
1dc50 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 ted, but.** they
1dc60 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 were reported b
1dc70 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 ack as [SQLITE_C
1dc80 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b ANTOPEN] or.** [
1dc90 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 SQLITE_IOERR] ra
1dca0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
1dcb0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 E_NOMEM]..**.**
1dcc0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 The pointer argu
1dcd0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 ments to [sqlite
1dce0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 3_free()] and [s
1dcf0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1dd00 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 ].** must be eit
1dd10 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 her NULL or else
1dd20 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e pointers obtain
1dd30 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a ed from a prior.
1dd40 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ** invocation of
1dd50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1dd60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1dd70 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 realloc()] that
1dd80 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 have.** not yet
1dd90 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a been released..*
1dda0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
1ddb0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 tion must not re
1ddc0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 ad or write any
1ddd0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f part of.** a blo
1dde0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 ck of memory aft
1ddf0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 er it has been r
1de00 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a eleased using.**
1de10 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1de20 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
1de30 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c alloc()]..*/.SQL
1de40 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 ITE_API void *SQ
1de50 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1de60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 ite3_malloc(int)
1de70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
1de80 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
1de90 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 L sqlite3_malloc
1dea0 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 64(sqlite3_uint6
1deb0 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 4);.SQLITE_API v
1dec0 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 oid *SQLITE_STDC
1ded0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c ALL sqlite3_real
1dee0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b loc(void*, int);
1def0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
1df00 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
1df10 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1df20 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 64(void*, sqlite
1df30 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 3_uint64);.SQLIT
1df40 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 E_API void SQLIT
1df50 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
1df60 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 3_free(void*);.S
1df70 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
1df80 33 5f 75 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 3_uint64 SQLITE_
1df90 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
1dfa0 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f msize(void*);../
1dfb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
1dfc0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 emory Allocator
1dfd0 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a Statistics.**.**
1dfe0 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 SQLite provides
1dff0 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 these two inter
1e000 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 faces for report
1e010 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 ing on the statu
1e020 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c s.** of the [sql
1e030 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 ite3_malloc()],
1e040 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1e050 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 , and [sqlite3_r
1e060 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 ealloc()].** rou
1e070 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 tines, which for
1e080 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d m the built-in m
1e090 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1e0a0 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a subsystem..**.*
1e0b0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
1e0c0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 memory_used()] r
1e0d0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
1e0e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
1e0f0 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 es.** of memory
1e100 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 currently outsta
1e110 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 nding (malloced
1e120 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a but not freed)..
1e130 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
1e140 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
1e150 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 r()] routine ret
1e160 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d urns the maximum
1e170 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 .** value of [sq
1e180 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
1e190 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 d()] since the h
1e1a0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
1e1b0 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 * was last reset
1e1c0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 . ^The values r
1e1d0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
1e1e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
1e1f0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
1e200 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
1e210 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 ter()] include a
1e220 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 ny overhead.** a
1e230 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 dded by SQLite i
1e240 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 n its implementa
1e250 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
1e260 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 _malloc()],.** b
1e270 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 ut not overhead
1e280 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 added by the any
1e290 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 underlying syst
1e2a0 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f em library.** ro
1e2b0 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c utines that [sql
1e2c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d ite3_malloc()] m
1e2d0 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e ay call..**.** ^
1e2e0 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d The memory high-
1e2f0 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 water mark is re
1e300 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 set to the curre
1e310 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b nt value of.** [
1e320 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
1e330 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e sed()] if and on
1e340 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 ly if the parame
1e350 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ter to.** [sqlit
1e360 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
1e370 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 ter()] is true.
1e380 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 ^The value retu
1e390 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 rned.** by [sqli
1e3a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
1e3b0 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 ater(1)] is the
1e3c0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a high-water mark.
1e3d0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 ** prior to the
1e3e0 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 reset..*/.SQLITE
1e3f0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
1e400 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 64 SQLITE_STDCAL
1e410 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 L sqlite3_memory
1e420 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c _used(void);.SQL
1e430 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
1e440 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 int64 SQLITE_STD
1e450 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d CALL sqlite3_mem
1e460 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e ory_highwater(in
1e470 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f t resetFlag);../
1e480 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 *.** CAPI3REF: P
1e490 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d seudo-Random Num
1e4a0 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a ber Generator.**
1e4b0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 .** SQLite conta
1e4c0 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 ins a high-quali
1e4d0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d ty pseudo-random
1e4e0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f number generato
1e4f0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f r (PRNG) used to
1e500 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f .** select rando
1e510 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 m [ROWID | ROWID
1e520 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e s] when insertin
1e530 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e g new records in
1e540 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a to a table that.
1e550 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 ** already uses
1e560 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 the largest poss
1e570 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 ible [ROWID]. T
1e580 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 he PRNG is also
1e590 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 used for.** the
1e5a0 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 build-in random(
1e5b0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 ) and randomblob
1e5c0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 () SQL functions
1e5d0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 . This interfac
1e5e0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c e allows.** appl
1e5f0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 ications to acce
1e600 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 ss the same PRNG
1e610 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f for other purpo
1e620 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 ses..**.** ^A ca
1e630 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 ll to this routi
1e640 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 ne stores N byte
1e650 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 s of randomness
1e660 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a into buffer P..*
1e670 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 * ^The P paramet
1e680 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c er can be a NULL
1e690 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
1e6a0 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ^If this routine
1e6b0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 has not been pr
1e6c0 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 eviously called
1e6d0 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f or if the previo
1e6e0 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e us.** call had N
1e6f0 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f less than one o
1e700 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
1e710 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 for P, then the
1e720 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 PRNG is.** seed
1e730 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e ed using randomn
1e740 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ess obtained fro
1e750 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 m the xRandomnes
1e760 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 s method of.** t
1e770 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
1e780 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
1e790 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 .** ^If the prev
1e7a0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 ious call to thi
1e7b0 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e s routine had an
1e7c0 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 N of 1 or more
1e7d0 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c and a.** non-NUL
1e7e0 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 L P then the pse
1e7f0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 udo-randomness i
1e800 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 s generated.** i
1e810 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 nternally and wi
1e820 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 thout recourse t
1e830 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
1e840 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a fs] xRandomness.
1e850 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 ** method..*/.SQ
1e860 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 LITE_API void SQ
1e870 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1e880 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 ite3_randomness(
1e890 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b int N, void *P);
1e8a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1e8b0 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 : Compile-Time A
1e8c0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c uthorization Cal
1e8d0 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 lbacks.** METHOD
1e8e0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
1e8f0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 ^This routine re
1e900 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f gisters an autho
1e910 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 rizer callback w
1e920 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 ith a particular
1e930 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
1e940 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c nnection], suppl
1e950 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 ied in the first
1e960 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 argument..** ^T
1e970 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
1e980 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
1e990 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 d as SQL stateme
1e9a0 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f nts are being co
1e9b0 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 mpiled.** by [sq
1e9c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
1e9d0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
1e9e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1e9f0 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c e_v2()],.** [sql
1ea00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
1ea10 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
1ea20 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 repare16_v2()].
1ea30 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 ^At various.**
1ea40 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 points during th
1ea50 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 e compilation pr
1ea60 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 ocess, as logic
1ea70 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 is being created
1ea80 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 .** to perform v
1ea90 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 arious actions,
1eaa0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
1eab0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
1eac0 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 ed to.** see if
1ead0 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 those actions ar
1eae0 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 e allowed. ^The
1eaf0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1eb00 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 back should.** r
1eb10 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
1eb20 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 ] to allow the a
1eb30 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 ction, [SQLITE_I
1eb40 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c GNORE] to disall
1eb50 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 ow the.** specif
1eb60 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c ic action but al
1eb70 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 low the SQL stat
1eb80 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 ement to continu
1eb90 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 e to be.** compi
1eba0 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f led, or [SQLITE_
1ebb0 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 DENY] to cause t
1ebc0 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 he entire SQL st
1ebd0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a atement to be.**
1ebe0 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 rejected with a
1ebf0 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 n error. ^If th
1ec00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1ec10 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a lback returns.**
1ec20 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 any value other
1ec30 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 than [SQLITE_IG
1ec40 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f NORE], [SQLITE_O
1ec50 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 K], or [SQLITE_D
1ec60 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ENY].** then the
1ec70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1ec80 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 e_v2()] or equiv
1ec90 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 alent call that
1eca0 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 triggered.** the
1ecb0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c authorizer will
1ecc0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 fail with an er
1ecd0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a ror message..**.
1ece0 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c ** When the call
1ecf0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
1ed00 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d LITE_OK], that m
1ed10 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 eans the operati
1ed20 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 on.** requested
1ed30 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 is ok. ^When th
1ed40 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
1ed50 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d ns [SQLITE_DENY]
1ed60 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 , the.** [sqlite
1ed70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1ed80 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 or equivalent ca
1ed90 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 ll that triggere
1eda0 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 d the.** authori
1edb0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 zer will fail wi
1edc0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 th an error mess
1edd0 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 age explaining t
1ede0 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 hat.** access is
1edf0 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 denied. .**.**
1ee00 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d ^The first param
1ee10 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 eter to the auth
1ee20 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1ee30 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
1ee40 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 third.** parame
1ee50 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
1ee60 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1ee70 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e r() interface. ^
1ee80 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
1ee90 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 eter.** to the c
1eea0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e allback is an in
1eeb0 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f teger [SQLITE_CO
1eec0 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 PY | action code
1eed0 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 ] that specifies
1eee0 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c .** the particul
1eef0 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 ar action to be
1ef00 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 authorized. ^The
1ef10 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 third through s
1ef20 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a ixth parameters.
1ef30 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 ** to the callba
1ef40 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d ck are zero-term
1ef50 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 inated strings t
1ef60 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 hat contain addi
1ef70 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c tional.** detail
1ef80 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 s about the acti
1ef90 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 on to be authori
1efa0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 zed..**.** ^If t
1efb0 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 he action code i
1efc0 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a s [SQLITE_READ].
1efd0 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 ** and the callb
1efe0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
1eff0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e ITE_IGNORE] then
1f000 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
1f010 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 d statement] sta
1f020 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 tement is constr
1f030 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 ucted to substit
1f040 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 ute.** a NULL va
1f050 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 lue in place of
1f060 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e the table column
1f070 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 that would have
1f080 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 .** been read if
1f090 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 [SQLITE_OK] had
1f0a0 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 been returned.
1f0b0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e The [SQLITE_IGN
1f0c0 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 ORE].** return c
1f0d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 an be used to de
1f0e0 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 ny an untrusted
1f0f0 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 user access to i
1f100 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c ndividual.** col
1f110 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e umns of a table.
1f120 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 .** ^If the acti
1f130 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 on code is [SQLI
1f140 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 TE_DELETE] and t
1f150 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
1f160 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 rns.** [SQLITE_I
1f170 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 GNORE] then the
1f180 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 [DELETE] operati
1f190 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 on proceeds but
1f1a0 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 the.** [truncate
1f1b0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 optimization] i
1f1c0 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 s disabled and a
1f1d0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 ll rows are dele
1f1e0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 ted individually
1f1f0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f ..**.** An autho
1f200 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 rizer is used wh
1f210 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 en [sqlite3_prep
1f220 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d are | preparing]
1f230 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
1f240 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 ts from an untru
1f250 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 sted source, to
1f260 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 ensure that the
1f270 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
1f280 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 * do not try to
1f290 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 access data they
1f2a0 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 are not allowed
1f2b0 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 to see, or that
1f2c0 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 they do not.**
1f2d0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d try to execute m
1f2e0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 alicious stateme
1f2f0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 nts that damage
1f300 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 the database. F
1f310 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 or.** example, a
1f320 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 n application ma
1f330 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 y allow a user t
1f340 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 o enter arbitrar
1f350 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 y.** SQL queries
1f360 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 for evaluation
1f370 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 by a database.
1f380 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 But the applicat
1f390 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 ion does.** not
1f3a0 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f want the user to
1f3b0 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 be able to make
1f3c0 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 arbitrary chang
1f3d0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 es to the.** dat
1f3e0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f abase. An autho
1f3f0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e rizer could then
1f400 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 be put in place
1f410 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 while the.** us
1f420 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 er-entered SQL i
1f430 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 s being [sqlite3
1f440 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
1f450 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 red] that.** dis
1f460 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e allows everythin
1f470 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 g except [SELECT
1f480 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a ] statements..**
1f490 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 .** Applications
1f4a0 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 that need to pr
1f4b0 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 ocess SQL from u
1f4c0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 ntrusted sources
1f4d0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 .** might also c
1f4e0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 onsider lowering
1f4f0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 resource limits
1f500 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
1f510 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 limit()].** and
1f520 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 limiting databas
1f530 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 e size using the
1f540 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 [max_page_count
1f550 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e ] [PRAGMA].** in
1f560 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 addition to usi
1f570 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 ng an authorizer
1f580 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 ..**.** ^(Only a
1f590 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a single authoriz
1f5a0 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 er can be in pla
1f5b0 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 ce on a database
1f5c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 connection.** a
1f5d0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 t a time. Each
1f5e0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
1f5f0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f set_authorizer o
1f600 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 verrides the.**
1f610 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e previous call.)^
1f620 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 ^Disable the a
1f630 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 uthorizer by ins
1f640 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 talling a NULL c
1f650 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 allback..** The
1f660 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 authorizer is di
1f670 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
1f680 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 t..**.** The aut
1f690 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1f6a0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 must not do any
1f6b0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 thing that will
1f6c0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 modify.** the da
1f6d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1f6e0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
1f6f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
1f700 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 llback..** Note
1f710 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
1f720 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
1f730 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1f740 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
1f750 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
1f760 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
1f770 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
1f780 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
1f790 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
1f7a0 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 ^When [sqlite3_p
1f7b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 repare_v2()] is
1f7c0 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 used to prepare
1f7d0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 a statement, the
1f7e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 .** statement mi
1f7f0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 ght be re-prepar
1f800 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 ed during [sqlit
1f810 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 e3_step()] due t
1f820 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 o a .** schema c
1f830 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 hange. Hence, t
1f840 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
1f850 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 hould ensure tha
1f860 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 t the.** correct
1f870 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1f880 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 back remains in
1f890 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 place during the
1f8a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1f8b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 ]..**.** ^Note t
1f8c0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a hat the authoriz
1f8d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
1f8e0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 nvoked only duri
1f8f0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ng.** [sqlite3_p
1f900 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 repare()] or its
1f910 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 variants. Auth
1f920 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 orization is not
1f930 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 .** performed du
1f940 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 ring statement e
1f950 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 valuation in [sq
1f960 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 lite3_step()], u
1f970 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 nless.** as stat
1f980 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f ed in the previo
1f990 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 us paragraph, sq
1f9a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 lite3_step() inv
1f9b0 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f okes.** sqlite3_
1f9c0 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 prepare_v2() to
1f9d0 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 reprepare a stat
1f9e0 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 ement after a sc
1f9f0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a hema change..*/.
1fa00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
1fa10 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
1fa20 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
1fa30 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a izer(. sqlite3*
1fa40 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 ,. int (*xAuth)
1fa50 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
1fa60 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
1fa70 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
1fa80 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 onst char*),. v
1fa90 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 oid *pUserData.)
1faa0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1fab0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 F: Authorizer Re
1fac0 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a turn Codes.**.**
1fad0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
1fae0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
1faf0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1fb00 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 ck function] mus
1fb10 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 t.** return eith
1fb20 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f er [SQLITE_OK] o
1fb30 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 r one of these t
1fb40 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 wo constants in
1fb50 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e order.** to sign
1fb60 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 al SQLite whethe
1fb70 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 r or not the act
1fb80 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 ion is permitted
1fb90 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 . See the.** [s
1fba0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1fbb0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
1fbc0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e er documentation
1fbd0 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c ] for additional
1fbe0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e .** information.
1fbf0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
1fc00 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 SQLITE_IGNORE i
1fc10 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 s also used as a
1fc20 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c [conflict resol
1fc30 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 ution mode].** r
1fc40 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 eturned from the
1fc50 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f [sqlite3_vtab_o
1fc60 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e n_conflict()] in
1fc70 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 terface..*/.#def
1fc80 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 ine SQLITE_DENY
1fc90 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 1 /* Abort t
1fca0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
1fcb0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a with an error *
1fcc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1fcd0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 _IGNORE 2 /* D
1fce0 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 on't allow acces
1fcf0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e s, but don't gen
1fd00 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a erate an error *
1fd10 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
1fd20 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 F: Authorizer Ac
1fd30 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a tion Codes.**.**
1fd40 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
1fd50 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 t_authorizer()]
1fd60 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
1fd70 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ers a callback f
1fd80 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 unction.** that
1fd90 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 is invoked to au
1fda0 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 thorize certain
1fdb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 SQL statement ac
1fdc0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 tions. The.** s
1fdd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1fde0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
1fdf0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f is an integer co
1fe00 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 de that specifie
1fe10 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e s.** what action
1fe20 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 is being author
1fe30 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 ized. These are
1fe40 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 the integer act
1fe50 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a ion codes that.*
1fe60 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
1fe70 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 callback may be
1fe80 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 passed..**.** T
1fe90 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 hese action code
1fea0 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 values signify
1feb0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 what kind of ope
1fec0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a ration is to be.
1fed0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ** authorized.
1fee0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 The 3rd and 4th
1fef0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
1ff00 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a e authorization.
1ff10 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 ** callback func
1ff20 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 tion will be par
1ff30 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 ameters or NULL
1ff40 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 depending on whi
1ff50 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 ch of these.** c
1ff60 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 odes is used as
1ff70 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
1ff80 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 eter. ^(The 5th
1ff90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1ffa0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 e.** authorizer
1ffb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
1ffc0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
1ffd0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 base ("main", "t
1ffe0 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 emp",.** etc.) i
1fff0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 f applicable.)^
20000 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 ^The 6th parame
20010 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
20020 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a rizer callback.*
20030 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 * is the name of
20040 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 the inner-most
20050 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 trigger or view
20060 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 that is responsi
20070 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 ble for.** the a
20080 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 ccess attempt or
20090 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 NULL if this ac
200a0 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 cess attempt is
200b0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a directly from.**
200c0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 top-level SQL c
200d0 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a ode..*/./*******
200e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
200f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
20100 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a **** 3rd *******
20110 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a ***** 4th ******
20120 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 *****/.#define S
20130 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 QLITE_CREATE_IND
20140 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 EX 1
20150 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
20160 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
20170 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20180 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c LITE_CREATE_TABL
20190 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f E 2 /
201a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
201b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
201c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
201d0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
201e0 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a INDEX 3 /*
201f0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
20200 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
20210 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20220 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
20230 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 ABLE 4 /*
20240 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
20250 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
20260 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20270 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 E_CREATE_TEMP_TR
20280 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 IGGER 5 /* T
20290 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
202a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
202b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
202c0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 _CREATE_TEMP_VIE
202d0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 W 6 /* Vi
202e0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
202f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
20300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20310 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 CREATE_TRIGGER
20320 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 7 /* Tri
20330 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
20340 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
20350 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
20360 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 REATE_VIEW
20370 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 8 /* View
20380 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
20390 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
203a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
203b0 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
203c0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 9 /* Table
203d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
203e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
203f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
20400 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 P_INDEX
20410 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 10 /* Index
20420 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
20430 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
20440 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
20450 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
20460 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 11 /* Table N
20470 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
20480 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
20490 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
204a0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 TEMP_INDEX
204b0 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 12 /* Index Na
204c0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
204d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
204e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
204f0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 EMP_TABLE 1
20500 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 3 /* Table Nam
20510 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
20520 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
20530 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
20540 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 MP_TRIGGER 14
20550 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
20560 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
20570 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
20580 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
20590 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 P_VIEW 15
205a0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
205b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
205c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
205d0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 SQLITE_DROP_TRIG
205e0 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 GER 16
205f0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
20600 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
20610 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
20620 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 QLITE_DROP_VIEW
20630 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 17
20640 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
20650 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
20660 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20670 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 LITE_INSERT
20680 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 18 /
20690 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
206a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
206b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
206c0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 ITE_PRAGMA
206d0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 19 /*
206e0 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 Pragma Name
206f0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 1st arg or NULL
20700 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20710 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 TE_READ
20720 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 20 /*
20730 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
20740 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
20750 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20760 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 E_SELECT
20770 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 21 /* N
20780 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e ULL N
20790 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
207a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
207b0 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 _TRANSACTION
207c0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 22 /* Op
207d0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 eration NU
207e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
207f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20800 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 UPDATE
20810 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 23 /* Tab
20820 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c le Name Col
20830 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a umn Name */.
20840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
20850 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 TTACH
20860 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 24 /* File
20870 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c name NULL
20880 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
20890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
208a0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 TACH
208b0 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 25 /* Datab
208c0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 ase Name NULL
208d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
208e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 efine SQLITE_ALT
208f0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 ER_TABLE
20900 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 26 /* Databa
20910 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 se Name Table
20920 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
20930 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e fine SQLITE_REIN
20940 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 DEX
20950 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 27 /* Index N
20960 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
20970 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
20980 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 ine SQLITE_ANALY
20990 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ZE
209a0 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 28 /* Table Na
209b0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
209c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
209d0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
209e0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 _VTABLE 2
209f0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 9 /* Table Nam
20a00 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
20a10 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
20a20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 e SQLITE_DROP_VT
20a30 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 ABLE 30
20a40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
20a50 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d Module Nam
20a60 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
20a70 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e SQLITE_FUNCTION
20a80 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 31
20a90 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
20aa0 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 Function Na
20ab0 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 me */.#define
20ac0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 SQLITE_SAVEPOINT
20ad0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 32
20ae0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 /* Operation
20af0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 Savepoint Na
20b00 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 me */.#define S
20b10 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 QLITE_COPY
20b20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 0
20b30 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 /* No longer use
20b40 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
20b50 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 ITE_RECURSIVE
20b60 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 33 /*
20b70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
20b80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
20b90 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
20ba0 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 REF: Tracing And
20bb0 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 Profiling Funct
20bc0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ions.** METHOD:
20bd0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 sqlite3.**.** Th
20be0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 ese routines reg
20bf0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 ister callback f
20c00 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 unctions that ca
20c10 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a n be used for.**
20c20 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f tracing and pro
20c30 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 filing the execu
20c40 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 tion of SQL stat
20c50 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ements..**.** ^T
20c60 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
20c70 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
20c80 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 by sqlite3_trace
20c90 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 () is invoked at
20ca0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 .** various time
20cb0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 s when an SQL st
20cc0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 atement is being
20cd0 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 run by [sqlite3
20ce0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 _step()]..** ^Th
20cf0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 e sqlite3_trace(
20d00 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e ) callback is in
20d10 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 voked with a UTF
20d20 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 -8 rendering of
20d30 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 the.** SQL state
20d40 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 ment text as the
20d50 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 statement first
20d60 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e begins executin
20d70 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e g..** ^(Addition
20d80 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 al sqlite3_trace
20d90 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 () callbacks mig
20da0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 ht occur.** as e
20db0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 ach triggered su
20dc0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 bprogram is ente
20dd0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 red. The callba
20de0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 cks for triggers
20df0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 .** contain a UT
20e00 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 F-8 SQL comment
20e10 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 that identifies
20e20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a the trigger.)^.*
20e30 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 *.** The [SQLITE
20e40 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 _TRACE_SIZE_LIMI
20e50 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 T] compile-time
20e60 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
20e70 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 ed to limit.** t
20e80 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f he length of [bo
20e90 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 und parameter] e
20ea0 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 xpansion in the
20eb0 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 output of sqlite
20ec0 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 3_trace()..**.**
20ed0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 ^The callback f
20ee0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
20ef0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 ed by sqlite3_pr
20f00 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b ofile() is invok
20f10 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 ed.** as each SQ
20f20 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 L statement fini
20f30 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 shes. ^The prof
20f40 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e ile callback con
20f50 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 tains.** the ori
20f60 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 ginal statement
20f70 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 text and an esti
20f80 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f mate of wall-clo
20f90 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f ck time.** of ho
20fa0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 w long that stat
20fb0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 ement took to ru
20fc0 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 n. ^The profile
20fd0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d callback.** tim
20fe0 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 e is in units of
20ff0 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f nanoseconds, ho
21000 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e wever the curren
21010 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e t implementation
21020 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 .** is only capa
21030 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f ble of milliseco
21040 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f nd resolution so
21050 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 the six least s
21060 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 ignificant.** di
21070 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 gits in the time
21080 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 are meaningless
21090 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
210a0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 ns of SQLite.**
210b0 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 might provide gr
210c0 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e eater resolution
210d0 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 on the profiler
210e0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a callback. The.
210f0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 ** sqlite3_profi
21100 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 le() function is
21110 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 considered expe
21120 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a rimental and is.
21130 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 ** subject to ch
21140 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 ange in future v
21150 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
21160 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
21170 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
21180 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 DCALL sqlite3_tr
21190 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f ace(sqlite3*, vo
211a0 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 id(*xTrace)(void
211b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 *,const char*),
211c0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 void*);.SQLITE_A
211d0 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 PI SQLITE_EXPERI
211e0 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53 51 4c MENTAL void *SQL
211f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
21200 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 te3_profile(sqli
21210 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 te3*,. void(*x
21220 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 Profile)(void*,c
21230 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 onst char*,sqlit
21240 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 e3_uint64), void
21250 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
21260 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 REF: Query Progr
21270 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ess Callbacks.**
21280 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
21290 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
212a0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e te3_progress_han
212b0 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e dler(D,N,X,P) in
212c0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 terface causes t
212d0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 he callback.** f
212e0 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 unction X to be
212f0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 invoked periodic
21300 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 ally during long
21310 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 running calls t
21320 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 o.** [sqlite3_ex
21330 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ec()], [sqlite3_
21340 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c step()] and [sql
21350 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
21360 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 ] for.** databas
21370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 e connection D.
21380 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 An example use
21390 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 for this.** inte
213a0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 rface is to keep
213b0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 a GUI updated d
213c0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 uring a large qu
213d0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ery..**.** ^The
213e0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 parameter P is p
213f0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 assed through as
21400 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
21410 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 ter to the .** c
21420 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
21430 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 X. ^The parame
21440 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 ter N is the app
21450 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 roximate number
21460 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 of .** [virtual
21470 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 machine instruct
21480 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 ions] that are e
21490 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e valuated between
214a0 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 successive.** i
214b0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
214c0 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e e callback X. ^
214d0 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 If N is less tha
214e0 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 n one then the p
214f0 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c rogress.** handl
21500 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a er is disabled..
21510 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 **.** ^Only a si
21520 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 ngle progress ha
21530 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 ndler may be def
21540 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 ined at one time
21550 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 per.** [databas
21560 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 e connection]; s
21570 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f etting a new pro
21580 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 gress handler ca
21590 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 ncels the.** old
215a0 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 one. ^Setting
215b0 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e parameter X to N
215c0 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 ULL disables the
215d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
215e0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 r..** ^The progr
215f0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 ess handler is a
21600 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 lso disabled by
21610 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 setting N to a v
21620 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 alue less.** tha
21630 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 n 1..**.** ^If t
21640 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c he progress call
21650 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e back returns non
21660 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 -zero, the opera
21670 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 tion is.** inter
21680 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 rupted. This fe
21690 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 ature can be use
216a0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 d to implement a
216b0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 .** "Cancel" but
216c0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f ton on a GUI pro
216d0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 gress dialog box
216e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 ..**.** The prog
216f0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c ress handler cal
21700 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 lback must not d
21710 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
21720 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
21730 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
21740 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
21750 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 ked the progress
21760 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 handler..** Not
21770 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
21780 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
21790 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
217a0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
217b0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
217c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
217d0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
217e0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
217f0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
21800 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
21810 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c d SQLITE_STDCALL
21820 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 sqlite3_progres
21830 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 s_handler(sqlite
21840 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 3*, int, int(*)(
21850 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a void*), void*);.
21860 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
21870 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 Opening A New D
21880 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
21890 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f on.** CONSTRUCTO
218a0 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a R: sqlite3.**.**
218b0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
218c0 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 open an SQLite
218d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 database file as
218e0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
218f0 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 e .** filename a
21900 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 rgument. ^The fi
21910 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 lename argument
21920 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
21930 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 s UTF-8 for.** s
21940 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
21950 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 d sqlite3_open_v
21960 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 2() and as UTF-1
21970 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 6 in the native
21980 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f byte.** order fo
21990 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 r sqlite3_open16
219a0 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 (). ^(A [databas
219b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
219c0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a ndle is usually.
219d0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a ** returned in *
219e0 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e ppDb, even if an
219f0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 error occurs.
21a00 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 The only excepti
21a10 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 on is that.** if
21a20 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c SQLite is unabl
21a30 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 e to allocate me
21a40 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
21a50 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
21a60 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c t,.** a NULL wil
21a70 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 l be written int
21a80 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 o *ppDb instead
21a90 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 of a pointer to
21aa0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a the [sqlite3].**
21ab0 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 object.)^ ^(If
21ac0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
21ad0 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 opened (and/or c
21ae0 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 reated) successf
21af0 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 ully, then.** [S
21b00 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 QLITE_OK] is ret
21b10 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 urned. Otherwis
21b20 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 e an [error code
21b30 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e ] is returned.)^
21b40 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 ^The.** [sqlite
21b50 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 3_errmsg()] or [
21b60 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
21b70 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e ()] routines can
21b80 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 be used to obta
21b90 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 in.** an English
21ba0 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 language descri
21bb0 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 ption of the err
21bc0 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 or following a f
21bd0 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a ailure of any.**
21be0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
21bf0 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e open() routines.
21c00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 .**.** ^The defa
21c10 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c ult encoding wil
21c20 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 l be UTF-8 for d
21c30 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 atabases created
21c40 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 using.** sqlite
21c50 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 3_open() or sqli
21c60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 te3_open_v2().
21c70 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 ^The default enc
21c80 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 oding for databa
21c90 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 ses.** created u
21ca0 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 sing sqlite3_ope
21cb0 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 n16() will be UT
21cc0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
21cd0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
21ce0 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 *.** Whether or
21cf0 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 not an error occ
21d00 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f urs when it is o
21d10 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 pened, resources
21d20 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
21d30 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 ith the [databas
21d40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
21d50 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 ndle should be r
21d60 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 eleased by.** pa
21d70 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c ssing it to [sql
21d80 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 ite3_close()] wh
21d90 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 en it is no long
21da0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a er required..**.
21db0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f ** The sqlite3_o
21dc0 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 pen_v2() interfa
21dd0 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 ce works like sq
21de0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 lite3_open().**
21df0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 except that it a
21e00 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 ccepts two addit
21e10 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 ional parameters
21e20 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
21e30 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 control.** over
21e40 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 the new database
21e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 connection. ^(
21e60 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 The flags parame
21e70 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 ter to.** sqlite
21e80 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 3_open_v2() can
21e90 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 take one of.** t
21ea0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 he following thr
21eb0 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f ee values, optio
21ec0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 nally combined w
21ed0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ith the .** [SQL
21ee0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
21ef0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ], [SQLITE_OPEN_
21f00 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c FULLMUTEX], [SQL
21f10 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
21f20 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 ACHE],.** [SQLIT
21f30 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
21f40 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 CHE], and/or [SQ
21f50 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 LITE_OPEN_URI] f
21f60 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 lags:)^.**.** <d
21f70 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c l>.** ^(<dt>[SQL
21f80 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
21f90 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 Y]</dt>.** <dd>T
21fa0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
21fb0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e pened in read-on
21fc0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 ly mode. If the
21fd0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e database does n
21fe0 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 ot.** already ex
21ff0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 ist, an error is
22000 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 returned.</dd>)
22010 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 ^.**.** ^(<dt>[S
22020 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
22030 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 RITE]</dt>.** <d
22040 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
22050 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
22060 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
22070 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 if possible, or
22080 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 reading.** only
22090 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 if the file is
220a0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 write protected
220b0 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 by the operating
220c0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 system. In eit
220d0 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 her.** case the
220e0 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c database must al
220f0 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 ready exist, oth
22100 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 erwise an error
22110 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 is returned.</dd
22120 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e >)^.**.** ^(<dt>
22130 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
22140 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 DWRITE] | [SQLIT
22150 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f E_OPEN_CREATE]</
22160 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
22170 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
22180 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e d for reading an
22190 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 d writing, and i
221a0 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 s created if.**
221b0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 it does not alre
221c0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 ady exist. This
221d0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 is the behavior
221e0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 that is always u
221f0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 sed for.** sqlit
22200 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
22210 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c lite3_open16().<
22220 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a /dd>)^.** </dl>.
22230 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 **.** If the 3rd
22240 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
22250 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
22260 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 is not one of th
22270 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e e.** combination
22280 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 s shown above op
22290 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 tionally combine
222a0 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 d with other.**
222b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
222c0 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f DONLY | SQLITE_O
222d0 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 PEN_* bits].** t
222e0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
222f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
22300 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 *.** ^If the [SQ
22310 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
22320 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 X] flag is set,
22330 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
22340 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
22350 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c opens in the mul
22360 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 ti-thread [threa
22370 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f ding mode] as lo
22380 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 ng as the single
22390 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 -thread.** mode
223a0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 has not been set
223b0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 at compile-time
223c0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 or start-time.
223d0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c ^If the.** [SQL
223e0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
223f0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 EX] flag is set
22400 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
22410 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 e connection ope
22420 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 ns.** in the ser
22430 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
22440 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 ng mode] unless
22450 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 single-thread wa
22460 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 s.** previously
22470 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 selected at comp
22480 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 ile-time or star
22490 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 t-time..** ^The
224a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 [SQLITE_OPEN_SHA
224b0 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 REDCACHE] flag c
224c0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 auses the databa
224d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f se connection to
224e0 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 be.** eligible
224f0 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 to use [shared c
22500 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 ache mode], rega
22510 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
22520 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a r or not shared.
22530 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 ** cache is enab
22540 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 led using [sqlit
22550 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 e3_enable_shared
22560 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 _cache()]. ^The
22570 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
22580 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 _PRIVATECACHE] f
22590 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 lag causes the d
225a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
225b0 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 on to not.** par
225c0 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 ticipate in [sha
225d0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 red cache mode]
225e0 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e even if it is en
225f0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 abled..**.** ^Th
22600 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
22610 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
22620 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e en_v2() is the n
22630 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ame of the.** [s
22640 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
22650 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
22660 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
22670 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 stem interface t
22680 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 hat.** the new d
22690 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
226a0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 on should use.
226b0 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 ^If the fourth p
226c0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 arameter is.** a
226d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
226e0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b en the default [
226f0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
22700 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a ect is used..**.
22710 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e ** ^If the filen
22720 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a ame is ":memory:
22730 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 ", then a privat
22740 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d e, temporary in-
22750 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a memory database.
22760 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f ** is created fo
22770 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e r the connection
22780 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f . ^This in-memo
22790 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c ry database will
227a0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 vanish when.**
227b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
227c0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
227d0 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 d. Future versi
227e0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 ons of SQLite mi
227f0 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 ght.** make use
22800 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 of additional sp
22810 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 ecial filenames
22820 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 that begin with
22830 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 the ":" characte
22840 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f r..** It is reco
22850 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 mmended that whe
22860 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c n a database fil
22870 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 ename actually d
22880 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a oes begin with.*
22890 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 * a ":" characte
228a0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 r you should pre
228b0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 fix the filename
228c0 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 with a pathname
228d0 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 such as.** "./"
228e0 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 to avoid ambigu
228f0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ity..**.** ^If t
22900 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 he filename is a
22910 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 n empty string,
22920 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 then a private,
22930 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d temporary.** on-
22940 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 disk database wi
22950 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 ll be created.
22960 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 ^This private da
22970 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a tabase will be.*
22980 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
22990 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 deleted as soon
229a0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 as the database
229b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
229c0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 osed..**.** [[UR
229d0 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 I filenames in s
229e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 qlite3_open()]]
229f0 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 <h3>URI Filename
22a00 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 s</h3>.**.** ^If
22a10 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 [URI filename]
22a20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 interpretation i
22a30 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 s enabled, and t
22a40 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
22a50 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 ment.** begins w
22a60 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 ith "file:", the
22a70 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 n the filename i
22a80 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
22a90 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 a URI. ^URI.**
22aa0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 filename interpr
22ab0 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c etation is enabl
22ac0 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 ed if the [SQLIT
22ad0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 E_OPEN_URI] flag
22ae0 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 is.** set in th
22af0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
22b00 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 t to sqlite3_ope
22b10 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 n_v2(), or if it
22b20 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 has.** been ena
22b30 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 bled globally us
22b40 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
22b50 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 CONFIG_URI] opti
22b60 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b on with the.** [
22b70 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
22b80 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 ] method or by t
22b90 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 he [SQLITE_USE_U
22ba0 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 RI] compile-time
22bb0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f option..** As o
22bc0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e f SQLite version
22bd0 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 3.7.7, URI file
22be0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 name interpretat
22bf0 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 ion is turned of
22c00 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c f.** by default,
22c10 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 but future rele
22c20 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d ases of SQLite m
22c30 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 ight enable URI
22c40 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 filename.** inte
22c50 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 rpretation by de
22c60 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 fault. See "[UR
22c70 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f I filenames]" fo
22c80 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
22c90 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
22ca0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 ** URI filenames
22cb0 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f are parsed acco
22cc0 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 rding to RFC 398
22cd0 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6. ^If the URI c
22ce0 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 ontains an.** au
22cf0 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 thority, then it
22d00 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
22d10 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 an empty string
22d20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a or the string .*
22d30 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e * "localhost". ^
22d40 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 If the authority
22d50 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 is not an empty
22d60 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 string or "loca
22d70 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 lhost", an .** e
22d80 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
22d90 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 to the caller.
22da0 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f ^The fragment co
22db0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 mponent of a URI
22dc0 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 , if .** present
22dd0 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a , is ignored..**
22de0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 .** ^SQLite uses
22df0 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e the path compon
22e00 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 ent of the URI a
22e10 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
22e20 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 e disk file.** w
22e30 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 hich contains th
22e40 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 e database. ^If
22e50 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 the path begins
22e60 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 with a '/' chara
22e70 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 cter, .** then i
22e80 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 t is interpreted
22e90 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 as an absolute
22ea0 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 path. ^If the pa
22eb0 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 th does not begi
22ec0 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 n .** with a '/'
22ed0 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 (meaning that t
22ee0 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 he authority sec
22ef0 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 tion is omitted
22f00 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a from the URI).**
22f10 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 then the path i
22f20 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
22f30 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 a relative path
22f40 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f . .** ^(On windo
22f50 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f ws, the first co
22f60 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 mponent of an ab
22f70 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 solute path .**
22f80 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 is a drive speci
22f90 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 fication (e.g. "
22fa0 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b C:").)^.**.** [[
22fb0 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 core URI query p
22fc0 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 arameters]].** T
22fd0 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 he query compone
22fe0 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 nt of a URI may
22ff0 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 contain paramete
23000 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 rs that are inte
23010 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 rpreted.** eithe
23020 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 r by SQLite itse
23030 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 lf, or by a [VFS
23040 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d | custom VFS im
23050 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a plementation]..*
23060 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 * SQLite and its
23070 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 built-in [VFSes
23080 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a ] interpret the.
23090 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 ** following que
230a0 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a ry parameters:.*
230b0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c *.** <ul>.** <
230c0 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 li> <b>vfs</b>:
230d0 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d ^The "vfs" param
230e0 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 eter may be used
230f0 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 to specify the
23100 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 name of.** a
23110 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 VFS object that
23120 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 provides the op
23130 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 erating system i
23140 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 nterface that sh
23150 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 ould.** be u
23160 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 sed to access th
23170 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
23180 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 on disk. ^If thi
23190 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 s option is set
231a0 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 to.** an emp
231b0 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 ty string the de
231c0 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 fault VFS object
231d0 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 is used. ^Speci
231e0 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e fying an unknown
231f0 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 .** VFS is a
23200 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c n error. ^If sql
23210 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
23220 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 s used and the v
23230 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 fs option is.**
23240 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 present, the
23250 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 n the VFS specif
23260 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f ied by the optio
23270 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e n takes preceden
23280 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 ce over.** t
23290 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 he value passed
232a0 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 as the fourth pa
232b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
232c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a e3_open_v2()..**
232d0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f .** <li> <b>mo
232e0 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f de</b>: ^(The mo
232f0 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 de parameter may
23300 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 be set to eithe
23310 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a r "ro", "rw",.**
23320 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 "rwc", or "
23330 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 memory". Attempt
23340 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f ing to set it to
23350 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 any other value
23360 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 is.** an er
23370 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e ror)^. .** ^
23380 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 If "ro" is speci
23390 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 fied, then the d
233a0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
233b0 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 d for read-only
233c0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 .** access,
233d0 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b just as if the [
233e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
233f0 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 ONLY] flag had b
23400 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a een set in the .
23410 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 ** third arg
23420 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
23430 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 _open_v2(). ^If
23440 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 the mode option
23450 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 is set to .**
23460 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 "rw", then the
23470 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
23480 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 ned for read-wri
23490 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 te (but not crea
234a0 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 te) .** acce
234b0 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 ss, as if SQLITE
234c0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 _OPEN_READWRITE
234d0 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f (but not SQLITE_
234e0 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 OPEN_CREATE) had
234f0 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 .** been se
23500 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 t. ^Value "rwc"
23510 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f is equivalent to
23520 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a setting both .*
23530 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 * SQLITE_OPE
23540 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 N_READWRITE and
23550 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
23560 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 TE. ^If the mod
23570 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 e option is.**
23580 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 set to "memor
23590 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b y" then a pure [
235a0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
235b0 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 se] that never r
235c0 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 eads.** or w
235d0 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 rites from disk
235e0 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 is used. ^It is
235f0 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 an error to spec
23600 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a ify a value for.
23610 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 ** the mode
23620 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 parameter that i
23630 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 s less restricti
23640 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 ve than that spe
23650 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 cified by.**
23660 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 the flags passe
23670 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 d in the third p
23680 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
23690 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a te3_open_v2()..*
236a0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 *.** <li> <b>c
236b0 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 ache</b>: ^The c
236c0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d ache parameter m
236d0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 ay be set to eit
236e0 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a her "shared" or.
236f0 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 ** "private"
23700 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f . ^Setting it to
23710 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 "shared" is equ
23720 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 ivalent to setti
23730 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 ng the.** SQ
23740 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
23750 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 CACHE bit in the
23760 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
23770 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 passed to.**
23780 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
23790 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 (). ^Setting the
237a0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 cache parameter
237b0 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 to "private" is
237c0 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c .** equival
237d0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 ent to setting t
237e0 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 he SQLITE_OPEN_P
237f0 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e RIVATECACHE bit.
23800 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 .** ^If sqli
23810 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
23820 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 used and the "c
23830 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 ache" parameter
23840 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a is present in.**
23850 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e a URI filen
23860 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f ame, its value o
23870 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 verrides any beh
23880 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 avior requested
23890 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 by setting.**
238a0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 SQLITE_OPEN_PR
238b0 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 IVATECACHE or SQ
238c0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
238d0 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a CACHE flag..**.*
238e0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c * <li> <b>psow<
238f0 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 /b>: ^The psow p
23900 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 arameter indicat
23910 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f es whether or no
23920 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f t the.** [po
23930 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 wersafe overwrit
23940 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 e] property does
23950 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 or does not app
23960 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 ly to the.**
23970 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f storage media o
23980 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 n which the data
23990 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 base file reside
239a0 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c s..**.** <li> <
239b0 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 b>nolock</b>: ^T
239c0 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 he nolock parame
239d0 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e ter is a boolean
239e0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
239f0 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 .** which if
23a00 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 set disables fi
23a10 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f le locking in ro
23a20 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d llback journal m
23a30 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 odes. This.**
23a40 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 is useful for
23a50 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 accessing a dat
23a60 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 abase on a files
23a70 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 ystem that does
23a80 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f not.** suppo
23a90 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 rt locking. Cau
23aa0 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 tion: Database
23ab0 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 corruption might
23ac0 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a result if two.*
23ad0 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 * or more pr
23ae0 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f ocesses write to
23af0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
23b00 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f se and any one o
23b10 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 f those.** p
23b20 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f rocesses uses no
23b30 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c lock=1..**.** <
23b40 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 li> <b>immutable
23b50 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 </b>: ^The immut
23b60 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 able parameter i
23b70 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 s a boolean quer
23b80 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 y.** paramet
23b90 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 er that indicate
23ba0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 s that the datab
23bb0 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 ase file is stor
23bc0 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 ed on.** rea
23bd0 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e d-only media. ^
23be0 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 When immutable i
23bf0 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 s set, SQLite as
23c00 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a sumes that the.*
23c10 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 * database f
23c20 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 ile cannot be ch
23c30 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 anged, even by a
23c40 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 process with hi
23c50 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 gher.** priv
23c60 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 ilege, and so th
23c70 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
23c80 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 ened read-only a
23c90 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a nd all locking.*
23ca0 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 * and change
23cb0 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 detection is di
23cc0 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e sabled. Caution
23cd0 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d : Setting the im
23ce0 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 mutable.** p
23cf0 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 roperty on a dat
23d00 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 abase file that
23d10 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 does in fact cha
23d20 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a nge can result.*
23d30 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 * in incorre
23d40 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 ct query results
23d50 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f and/or [SQLITE_
23d60 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e CORRUPT] errors.
23d70 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f .** See also
23d80 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f : [SQLITE_IOCAP_
23d90 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 IMMUTABLE]..**
23da0 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a .** </ul>.*
23db0 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 *.** ^Specifying
23dc0 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 an unknown para
23dd0 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 meter in the que
23de0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 ry component of
23df0 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a a URI is not an.
23e00 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 ** error. Futur
23e10 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
23e20 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 Lite might under
23e30 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c stand additional
23e40 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 query.** parame
23e50 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 ters. See "[que
23e60 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 ry parameters wi
23e70 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 th special meani
23e80 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 ng to SQLite]" f
23e90 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c or.** additional
23ea0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
23eb0 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 .** [[URI filena
23ec0 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 me examples]] <h
23ed0 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 3>URI filename e
23ee0 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a xamples</h3>.**.
23ef0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 ** <table border
23f00 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 ="1" align=cente
23f10 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e r cellpadding=5>
23f20 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 .** <tr><th> URI
23f30 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 filenames <th>
23f40 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c Results.** <tr><
23f50 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 td> file:data.db
23f60 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
23f70 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 Open the file
23f80 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 "data.db" in th
23f90 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 e current direct
23fa0 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ory..** <tr><td>
23fb0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 file:/home/fred
23fc0 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 /data.db<br>.**
23fd0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f file://
23fe0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
23ff0 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 db <br> .**
24000 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 file://loca
24010 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f lhost/home/fred/
24020 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 data.db <br> <td
24030 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f > .** O
24040 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
24050 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 file "/home/fre
24060 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c d/data.db"..** <
24070 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 tr><td> file://d
24080 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 arkstar/home/fre
24090 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a d/data.db <td> .
240a0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 ** An e
240b0 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 rror. "darkstar"
240c0 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e is not a recogn
240d0 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a ized authority..
240e0 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 ** <tr><td style
240f0 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f ="white-space:no
24100 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 wrap"> .**
24110 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 file:///C:/D
24120 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 ocuments%20and%2
24130 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 0Settings/fred/D
24140 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a esktop/data.db.*
24150 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f * <td> Windo
24160 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 ws only: Open th
24170 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 e file "data.db"
24180 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 on fred's deskt
24190 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 op on drive.**
241a0 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 C:. Note
241b0 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 that the %20 es
241c0 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 caping in this e
241d0 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 xample is not st
241e0 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 rictly .**
241f0 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 necessary -
24200 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 space characters
24210 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 can be used lit
24220 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 erally.**
24230 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 in URI filena
24240 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e mes..** <tr><td>
24250 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f file:data.db?mo
24260 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 de=ro&cache=priv
24270 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 ate <td> .**
24280 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 Open file
24290 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 "data.db" in the
242a0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f current directo
242b0 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 ry for read-only
242c0 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 access..**
242d0 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 Regardless
242e0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
242f0 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d t shared-cache m
24300 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 ode is enabled b
24310 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 y.** de
24320 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 fault, use a pri
24330 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c vate cache..** <
24340 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f tr><td> file:/ho
24350 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f me/fred/data.db?
24360 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 vfs=unix-dotfile
24370 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <td>.**
24380 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f Open file "/ho
24390 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 me/fred/data.db"
243a0 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 . Use the specia
243b0 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 l VFS "unix-dotf
243c0 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 ile".**
243d0 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 that uses dot-f
243e0 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 iles in place of
243f0 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 posix advisory
24400 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e locking..** <tr>
24410 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 <td> file:data.d
24420 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 b?mode=readonly
24430 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <td> .**
24440 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 An error. "rea
24450 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 donly" is not a
24460 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 valid option for
24470 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 the "mode" para
24480 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c meter..** </tabl
24490 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 e>.**.** ^URI he
244a0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 xadecimal escape
244b0 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 sequences (%HH)
244c0 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 are supported w
244d0 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 ithin the path a
244e0 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 nd.** query comp
244f0 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e onents of a URI.
24500 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 A hexadecimal e
24510 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 scape sequence c
24520 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 onsists of a.**
24530 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 percent sign - "
24540 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 %" - followed by
24550 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 exactly two hex
24560 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 adecimal digits
24570 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 .** specifying a
24580 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e n octet value. ^
24590 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 Before the path
245a0 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 or query compone
245b0 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 nts of a.** URI
245c0 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 filename are int
245d0 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 erpreted, they a
245e0 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 re encoded using
245f0 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a UTF-8 and all .
24600 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 ** hexadecimal e
24610 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 scape sequences
24620 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 replaced by a si
24630 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 ngle byte contai
24640 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 ning the.** corr
24650 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e esponding octet.
24660 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 If this process
24670 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e generates an in
24680 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f valid UTF-8 enco
24690 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 ding,.** the res
246a0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
246b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 ed..**.** <b>Not
246c0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 e to Windows use
246d0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 rs:</b> The enc
246e0 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 oding used for t
246f0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
24700 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 ment.** of sqlit
24710 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
24720 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
24730 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e must be UTF-8, n
24740 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 ot whatever.** c
24750 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 odepage is curre
24760 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 ntly defined. F
24770 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e ilenames contain
24780 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 ing internationa
24790 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 l.** characters
247a0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
247b0 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 d to UTF-8 prior
247c0 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d to passing them
247d0 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 into.** sqlite3
247e0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
247f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a e3_open_v2()..**
24800 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 .** <b>Note to W
24810 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 indows Runtime u
24820 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 sers:</b> The t
24830 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f emporary directo
24840 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a ry must be set.*
24850 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 * prior to calli
24860 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ng sqlite3_open(
24870 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 ) or sqlite3_ope
24880 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 n_v2(). Otherwi
24890 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 se, various.** f
248a0 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 eatures that req
248b0 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 uire the use of
248c0 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 temporary files
248d0 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 may fail..**.**
248e0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
248f0 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 e3_temp_director
24900 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 y].*/.SQLITE_API
24910 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
24920 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ALL sqlite3_open
24930 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a (. const char *
24940 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 filename, /* D
24950 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
24960 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 (UTF-8) */. sq
24970 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 lite3 **ppDb
24980 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
24990 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
249a0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 /.);.SQLITE_API
249b0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
249c0 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 LL sqlite3_open1
249d0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 6(. const void
249e0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
249f0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
24a00 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 e (UTF-16) */.
24a10 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
24a20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
24a30 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
24a40 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
24a50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
24a60 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 CALL sqlite3_ope
24a70 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 n_v2(. const ch
24a80 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 ar *filename,
24a90 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
24aa0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a name (UTF-8) */.
24ab0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
24ac0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 , /* OUT
24ad0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
24ae0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 le */. int flag
24af0 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 s,
24b00 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f /* Flags */. co
24b10 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 nst char *zVfs
24b20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 /* Name of
24b30 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 VFS module to u
24b40 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 se */.);../*.**
24b50 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e CAPI3REF: Obtain
24b60 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 Values For URI
24b70 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a Parameters.**.**
24b80 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 These are utili
24b90 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 ty routines, use
24ba0 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 ful to VFS imple
24bb0 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 mentations, that
24bc0 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 check.** to see
24bd0 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 if a database f
24be0 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 ile was a URI th
24bf0 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 at contained a s
24c00 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a pecific query .*
24c10 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 * parameter, and
24c20 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 if so obtains t
24c30 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 he value of that
24c40 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
24c50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 ..**.** If F is
24c60 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
24c70 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 ename pointer pa
24c80 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f ssed into the xO
24c90 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 pen() method of
24ca0 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d .** a VFS implem
24cb0 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 entation when th
24cc0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
24cd0 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 r to xOpen() has
24ce0 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 one or .** more
24cf0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f of the [SQLITE_
24d00 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 OPEN_URI] or [SQ
24d10 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 LITE_OPEN_MAIN_D
24d20 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a B] bits set and.
24d30 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 ** P is the name
24d40 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 of the query pa
24d50 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a rameter, then.**
24d60 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 sqlite3_uri_par
24d70 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 ameter(F,P) retu
24d80 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 rns the value of
24d90 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 the P.** parame
24da0 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 ter if it exists
24db0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 or a NULL point
24dc0 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 er if P does not
24dd0 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a appear as a .**
24de0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
24df0 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 on F. If P is
24e00 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 a query paramete
24e10 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f r of F.** has no
24e20 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c explicit value,
24e30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
24e40 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 i_parameter(F,P)
24e50 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f returns.** a po
24e60 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 inter to an empt
24e70 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 y string..**.**
24e80 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f The sqlite3_uri_
24e90 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 boolean(F,P,B) r
24ea0 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 outine assumes t
24eb0 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 hat P is a boole
24ec0 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 an.** parameter
24ed0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 and returns true
24ee0 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 (1) or false (0
24ef0 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 ) according to t
24f00 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 he value.** of P
24f10 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 . The sqlite3_u
24f20 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
24f30 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
24f40 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 s true (1) if th
24f50 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 e.** value of qu
24f60 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 ery parameter P
24f70 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c is one of "yes",
24f80 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 "true", or "on"
24f90 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 in any.** case
24fa0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 or if the value
24fb0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f begins with a no
24fc0 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 n-zero number.
24fd0 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f The .** sqlite3_
24fe0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
24ff0 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 B) routines retu
25000 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 rns false (0) if
25010 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a the value of.**
25020 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
25030 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f P is one of "no
25040 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 ", "false", or "
25050 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 off" in any case
25060 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 or.** if the va
25070 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 lue begins with
25080 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 a numeric zero.
25090 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 If P is not a q
250a0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 uery.** paramete
250b0 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 r on F or if the
250c0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 value of P is d
250d0 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e oes not match an
250e0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 y of the.** abov
250f0 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f e, then sqlite3_
25100 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
25110 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 B) returns (B!=0
25120 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )..**.** The sql
25130 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 ite3_uri_int64(F
25140 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f ,P,D) routine co
25150 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 nverts the value
25160 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 of P into a.**
25170 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
25180 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e teger and return
25190 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 s that integer,
251a0 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e or D if P does n
251b0 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 ot.** exist. If
251c0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
251d0 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 is something oth
251e0 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 er than an integ
251f0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f er, then.** zero
25200 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
25210 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e .** If F is a N
25220 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
25230 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 n sqlite3_uri_pa
25240 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 rameter(F,P) ret
25250 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a urns NULL and.**
25260 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
25270 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 lean(F,P,B) retu
25280 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 rns B. If F is
25290 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 not a NULL point
252a0 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 er and.** is not
252b0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
252c0 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 pathname pointe
252d0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 r that SQLite pa
252e0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f ssed into the xO
252f0 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f pen.** VFS metho
25300 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 d, then the beha
25310 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 vior of this rou
25320 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 tine is undefine
25330 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a d and probably.*
25340 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a * undesirable..*
25350 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
25360 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f st char *SQLITE_
25370 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
25380 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f uri_parameter(co
25390 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e nst char *zFilen
253a0 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 ame, const char
253b0 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 *zParam);.SQLITE
253c0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
253d0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
253e0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 uri_boolean(cons
253f0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 t char *zFile, c
25400 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 onst char *zPara
25410 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 m, int bDefault)
25420 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c ;.SQLITE_API sql
25430 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 ite3_int64 SQLIT
25440 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
25450 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 3_uri_int64(cons
25460 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 t char*, const c
25470 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e har*, sqlite3_in
25480 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 t64);.../*.** CA
25490 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f PI3REF: Error Co
254a0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 des And Messages
254b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
254c0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 te3.**.** ^If th
254d0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 e most recent sq
254e0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c lite3_* API call
254f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
25500 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 .** [database c
25510 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 onnection] D fai
25520 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 led, then the sq
25530 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 lite3_errcode(D)
25540 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 interface.** re
25550 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 turns the numeri
25560 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 c [result code]
25570 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 or [extended res
25580 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 ult code] for th
25590 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a at.** API call..
255a0 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 ** If the most r
255b0 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 ecent API call w
255c0 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a as successful,.*
255d0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 * then the retur
255e0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c n value from sql
255f0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 ite3_errcode() i
25600 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 s undefined..**
25610 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 ^The sqlite3_ext
25620 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a ended_errcode().
25630 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
25640 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 the same except
25650 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 that it always r
25660 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b eturns the .** [
25670 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
25680 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 code] even when
25690 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
256a0 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 codes are.** dis
256b0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 abled..**.** ^Th
256c0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 e sqlite3_errmsg
256d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 () and sqlite3_e
256e0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e rrmsg16() return
256f0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 English-languag
25700 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 e.** text that d
25710 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 escribes the err
25720 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 or, as either UT
25730 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 F-8 or UTF-16 re
25740 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e spectively..** ^
25750 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 (Memory to hold
25760 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
25770 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 e string is mana
25780 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a ged internally..
25790 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
257a0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 on does not need
257b0 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 to worry about
257c0 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 freeing the resu
257d0 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 lt..** However,
257e0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 the error string
257f0 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 might be overwr
25800 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 itten or dealloc
25810 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 ated by.** subse
25820 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f quent calls to o
25830 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
25840 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e rface functions.
25850 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 )^.**.** ^The sq
25860 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 lite3_errstr() i
25870 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
25880 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e the English-lan
25890 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 guage text.** th
258a0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 at describes the
258b0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 [result code],
258c0 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d as UTF-8..** ^(M
258d0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
258e0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
258f0 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 string is manage
25900 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 d internally.**
25910 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 and must not be
25920 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 freed by the app
25930 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a lication)^..**.*
25940 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 * When the seria
25950 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
25960 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 mode] is in use
25970 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 , it might be th
25980 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 e.** case that a
25990 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 second error oc
259a0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 curs on a separa
259b0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 te thread in bet
259c0 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 ween.** the time
259d0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 of the first er
259e0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c ror and the call
259f0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 to these interf
25a00 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 aces..** When th
25a10 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 at happens, the
25a20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c second error wil
25a30 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 l be reported si
25a40 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 nce these.** int
25a50 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 erfaces always r
25a60 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 eport the most r
25a70 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 ecent result. T
25a80 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c o avoid.** this,
25a90 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e each thread can
25aa0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 obtain exclusiv
25ab0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 e use of the [da
25ac0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
25ad0 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b n] D.** by invok
25ae0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
25af0 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 ex_enter]([sqlit
25b00 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 e3_db_mutex](D))
25b10 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e before beginnin
25b20 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e g.** to use D an
25b30 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 d invoking [sqli
25b40 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d te3_mutex_leave]
25b50 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 ([sqlite3_db_mut
25b60 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a ex](D)) after.**
25b70 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 all calls to th
25b80 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 e interfaces lis
25b90 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d ted here are com
25ba0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 pleted..**.** If
25bb0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 an interface fa
25bc0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f ils with SQLITE_
25bd0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 MISUSE, that mea
25be0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 ns the interface
25bf0 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 .** was invoked
25c00 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 incorrectly by t
25c10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 he application.
25c20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 In that case, t
25c30 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 he.** error code
25c40 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 and message may
25c50 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 or may not be s
25c60 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 et..*/.SQLITE_AP
25c70 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
25c80 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 CALL sqlite3_err
25c90 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 code(sqlite3 *db
25ca0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
25cb0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
25cc0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
25cd0 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 d_errcode(sqlite
25ce0 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 3 *db);.SQLITE_A
25cf0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 PI const char *S
25d00 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
25d10 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c lite3_errmsg(sql
25d20 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 ite3*);.SQLITE_A
25d30 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 PI const void *S
25d40 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
25d50 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 lite3_errmsg16(s
25d60 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 qlite3*);.SQLITE
25d70 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
25d80 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
25d90 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 sqlite3_errstr(i
25da0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
25db0 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 3REF: Prepared S
25dc0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a tatement Object.
25dd0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 ** KEYWORDS: {pr
25de0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
25df0 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 } {prepared stat
25e00 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e ements}.**.** An
25e10 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
25e20 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 s object represe
25e30 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c nts a single SQL
25e40 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a statement that.
25e50 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 ** has been comp
25e60 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 iled into binary
25e70 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 form and is rea
25e80 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 dy to be evaluat
25e90 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 ed..**.** Think
25ea0 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 of each SQL stat
25eb0 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 ement as a separ
25ec0 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f ate computer pro
25ed0 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 gram. The.** or
25ee0 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 iginal SQL text
25ef0 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 is source code.
25f00 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 A prepared stat
25f10 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a ement object .**
25f20 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 is the compiled
25f30 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 object code. A
25f40 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 ll SQL must be c
25f50 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a onverted into a.
25f60 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ** prepared stat
25f70 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 ement before it
25f80 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a can be run..**.*
25f90 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 * The life-cycle
25fa0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 of a prepared s
25fb0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
25fc0 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b usually goes lik
25fd0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f e this:.**.** <o
25fe0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 l>.** <li> Creat
25ff0 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 e the prepared s
26000 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
26010 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 using [sqlite3_p
26020 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a repare_v2()]..**
26030 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 <li> Bind value
26040 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 s to [parameters
26050 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 ] using the sqli
26060 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 te3_bind_*().**
26070 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e interfaces.
26080 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 .** <li> Run the
26090 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 SQL by calling
260a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
260b0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
260c0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 es..** <li> Rese
260d0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 t the prepared s
260e0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
260f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
26100 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a then go back.**
26110 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e to step 2.
26120 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f Do this zero o
26130 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a r more times..**
26140 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 <li> Destroy th
26150 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b e object using [
26160 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
26170 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f ()]..** </ol>.*/
26180 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
26190 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c sqlite3_stmt sql
261a0 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a ite3_stmt;../*.*
261b0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
261c0 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d time Limits.** M
261d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
261e0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 *.** ^(This inte
261f0 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 rface allows the
26200 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 size of various
26210 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 constructs to b
26220 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 e limited.** on
26230 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 a connection by
26240 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 connection basis
26250 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 . The first par
26260 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
26270 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
26280 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d ction] whose lim
26290 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 it is to be set
262a0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 or queried. The
262b0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
262c0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 eter is one of t
262d0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f he [limit catego
262e0 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e ries] that defin
262f0 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 e a.** class of
26300 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 constructs to be
26310 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 size limited.
26320 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
26330 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 ter is the.** ne
26340 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 w limit for that
26350 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a construct.)^.**
26360 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 .** ^If the new
26370 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 limit is a negat
26380 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 ive number, the
26390 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 limit is unchang
263a0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 ed..** ^(For eac
263b0 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 h limit category
263c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 SQLITE_LIMIT_<i
263d0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 >NAME</i> there
263e0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 is a .** [limits
263f0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f | hard upper bo
26400 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 und].** set at c
26410 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 ompile-time by a
26420 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
26430 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 macro called.**
26440 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 [limits | SQLITE
26450 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e _MAX_<i>NAME</i>
26460 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d ]..** (The "_LIM
26470 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 IT_" in the name
26480 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 is changed to "
26490 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 _MAX_".))^.** ^A
264a0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 ttempts to incre
264b0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 ase a limit abov
264c0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 e its hard upper
264d0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 bound are.** si
264e0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 lently truncated
264f0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 to the hard upp
26500 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 er bound..**.**
26510 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 ^Regardless of w
26520 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
26530 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e e limit was chan
26540 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 ged, the .** [sq
26550 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 lite3_limit()] i
26560 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
26570 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 the prior value
26580 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a of the limit..*
26590 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e * ^Hence, to fin
265a0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 d the current va
265b0 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 lue of a limit w
265c0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 ithout changing
265d0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e it,.** simply in
265e0 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 voke this interf
265f0 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 ace with the thi
26600 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 rd parameter set
26610 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 to -1..**.** Ru
26620 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 n-time limits ar
26630 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 e intended for u
26640 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f se in applicatio
26650 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a ns that manage.*
26660 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e * both their own
26670 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 internal databa
26680 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 se and also data
26690 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 bases that are c
266a0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 ontrolled.** by
266b0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e untrusted extern
266c0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 al sources. An
266d0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 example applicat
266e0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a ion might be a.*
266f0 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 * web browser th
26700 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 at has its own d
26710 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f atabases for sto
26720 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 ring history and
26730 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 .** separate dat
26740 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 abases controlle
26750 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 d by JavaScript
26760 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 applications dow
26770 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 nloaded.** off t
26780 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 he Internet. Th
26790 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 e internal datab
267a0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 ases can be give
267b0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 n the.** large,
267c0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 default limits.
267d0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 Databases manag
267e0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 ed by external s
267f0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 ources can.** be
26800 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c given much smal
26810 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 ler limits desig
26820 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 ned to prevent a
26830 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 denial of servi
26840 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 ce.** attack. D
26850 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 evelopers might
26860 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 also want to use
26870 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 the [sqlite3_se
26880 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a t_authorizer()].
26890 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 ** interface to
268a0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 further control
268b0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 untrusted SQL.
268c0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 The size of the
268d0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 database.** crea
268e0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 ted by an untrus
268f0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 ted script can b
26900 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e e contained usin
26910 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 g the.** [max_pa
26920 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d ge_count] [PRAGM
26930 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 A]..**.** New ru
26940 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 n-time limit cat
26950 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 egories may be a
26960 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
26970 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 eleases..*/.SQLI
26980 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
26990 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
269a0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 3_limit(sqlite3*
269b0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 , int id, int ne
269c0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 wVal);../*.** CA
269d0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
269e0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 Limit Categorie
269f0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
26a00 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 limit category}
26a10 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 {*limit categori
26a20 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 es}.**.** These
26a30 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
26a40 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d various perform
26a50 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 ance limits.** t
26a60 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 hat can be lower
26a70 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 ed at run-time u
26a80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 sing [sqlite3_li
26a90 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 mit()]..** The s
26aa0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d ynopsis of the m
26ab0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 eanings of the v
26ac0 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 arious limits is
26ad0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a shown below..**
26ae0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f Additional info
26af0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c rmation is avail
26b00 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 able at [limits
26b10 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 | Limits in SQLi
26b20 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a te]..**.** <dl>.
26b30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
26b40 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 T_LENGTH]] ^(<dt
26b50 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 >SQLITE_LIMIT_LE
26b60 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
26b70 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a >The maximum siz
26b80 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 e of any string
26b90 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 or BLOB or table
26ba0 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c row, in bytes.<
26bb0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
26bc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
26bd0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 ENGTH]] ^(<dt>SQ
26be0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
26bf0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
26c00 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
26c10 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 ngth of an SQL s
26c20 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 tatement, in byt
26c30 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a es.</dd>)^.**.**
26c40 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
26c50 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 COLUMN]] ^(<dt>S
26c60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
26c70 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 MN</dt>.** <dd>T
26c80 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
26c90 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
26ca0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 a table definiti
26cb0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 on or in the.**
26cc0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 result set of a
26cd0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 [SELECT] or the
26ce0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
26cf0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 f columns in an
26d00 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 index.** or in a
26d10 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 n ORDER BY or GR
26d20 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f OUP BY clause.</
26d30 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
26d40 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
26d50 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 DEPTH]] ^(<dt>SQ
26d60 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
26d70 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 DEPTH</dt>.** <d
26d80 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 d>The maximum de
26d90 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 pth of the parse
26da0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 tree on any exp
26db0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a ression.</dd>)^.
26dc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
26dd0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
26de0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c LECT]] ^(<dt>SQL
26df0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
26e00 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a ND_SELECT</dt>.*
26e10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
26e20 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d m number of term
26e30 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 s in a compound
26e40 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
26e50 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
26e60 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 [SQLITE_LIMIT_VD
26e70 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 BE_OP]] ^(<dt>SQ
26e80 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
26e90 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 OP</dt>.** <dd>T
26ea0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
26eb0 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e r of instruction
26ec0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d s in a virtual m
26ed0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a achine program.*
26ee0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d * used to implem
26ef0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 ent an SQL state
26f00 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 ment. This limi
26f10 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 t is not current
26f20 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 ly.** enforced,
26f30 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 though that migh
26f40 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f t be added in so
26f50 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 me future releas
26f60 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c e of.** SQLite.<
26f70 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
26f80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
26f90 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 TION_ARG]] ^(<dt
26fa0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 >SQLITE_LIMIT_FU
26fb0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a NCTION_ARG</dt>.
26fc0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
26fd0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 um number of arg
26fe0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 uments on a func
26ff0 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a tion.</dd>)^.**.
27000 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
27010 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c T_ATTACHED]] ^(<
27020 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
27030 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a ATTACHED</dt>.**
27040 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
27050 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 number of [ATTA
27060 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 CH | attached da
27070 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e tabases].)^</dd>
27080 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
27090 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
270a0 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e RN_LENGTH]].** ^
270b0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
270c0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
270d0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
270e0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
270f0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 ngth of the patt
27100 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ern argument to
27110 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a the [LIKE] or.**
27120 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 [GLOB] operator
27130 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 s.</dd>)^.**.**
27140 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 [[SQLITE_LIMIT_V
27150 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d ARIABLE_NUMBER]]
27160 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 .** ^(<dt>SQLITE
27170 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
27180 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c NUMBER</dt>.** <
27190 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 dd>The maximum i
271a0 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 ndex number of a
271b0 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 ny [parameter] i
271c0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
271d0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 nt.)^.**.** [[SQ
271e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
271f0 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 ER_DEPTH]] ^(<dt
27200 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 >SQLITE_LIMIT_TR
27210 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e IGGER_DEPTH</dt>
27220 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
27230 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 mum depth of rec
27240 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 ursion for trigg
27250 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ers.</dd>)^.**.*
27260 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
27270 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d _WORKER_THREADS]
27280 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
27290 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 IMIT_WORKER_THRE
272a0 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ADS</dt>.** <dd>
272b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
272c0 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 er of auxiliary
272d0 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 worker threads t
272e0 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 hat a single.**
272f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
27300 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c ent] may start.<
27310 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a /dd>)^.** </dl>.
27320 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
27330 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 E_LIMIT_LENGTH
27340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
27350 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
27360 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e TE_LIMIT_SQL_LEN
27370 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 GTH
27380 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
27390 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
273a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
273b0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
273c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
273d0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 DEPTH
273e0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
273f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
27400 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 OUND_SELECT
27410 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 4.#define
27420 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
27430 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 E_OP
27440 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 5.#define
27450 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 SQLITE_LIMIT_FU
27460 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 NCTION_ARG
27470 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 6.#defin
27480 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 e SQLITE_LIMIT_A
27490 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 TTACHED
274a0 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 7.#defi
274b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
274c0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
274d0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 GTH 8.#def
274e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
274f0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
27500 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 9.#de
27510 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
27520 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 T_TRIGGER_DEPTH
27530 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 10.#d
27540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
27550 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 IT_WORKER_THREAD
27560 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a S 11..
27570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
27580 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c Compiling An SQL
27590 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 Statement.** KE
275a0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 YWORDS: {SQL sta
275b0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d tement compiler}
275c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
275d0 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 te3.** CONSTRUCT
275e0 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OR: sqlite3_stmt
275f0 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 .**.** To execut
27600 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 e an SQL query,
27610 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 it must first be
27620 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 compiled into a
27630 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 byte-code.** pr
27640 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 ogram using one
27650 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
27660 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 s..**.** The fir
27670 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 st argument, "db
27680 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 ", is a [databas
27690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 e connection] ob
276a0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a tained from a.**
276b0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 prior successfu
276c0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
276d0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
276e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
276f0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f or.** [sqlite3_o
27700 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 pen16()]. The d
27710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
27720 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 on must not have
27730 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a been closed..**
27740 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
27750 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c rgument, "zSql",
27760 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e is the statemen
27770 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
27780 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 , encoded.** as
27790 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
277a0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c UTF-16. The sql
277b0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 ite3_prepare() a
277c0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
277d0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 re_v2().** inter
277e0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c faces use UTF-8,
277f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
27800 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c pare16() and sql
27810 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
27820 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 2().** use UTF-1
27830 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 6..**.** ^If the
27840 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 nByte argument
27850 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
27860 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 n zSql is read u
27870 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 p to the.** firs
27880 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f t zero terminato
27890 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 r. ^If nByte is
278a0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 positive, then i
278b0 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 t is the.** numb
278c0 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 er of bytes read
278d0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 from zSql. ^If
278e0 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 nByte is zero,
278f0 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 then no prepared
27900 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 .** statement is
27910 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 generated..** I
27920 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f f the caller kno
27930 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 ws that the supp
27940 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e lied string is n
27950 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 ul-terminated, t
27960 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 hen.** there is
27970 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 a small performa
27980 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f nce advantage to
27990 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 passing an nByt
279a0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 e parameter that
279b0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 .** is the numbe
279c0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
279d0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c e input string <
279e0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a i>including</i>.
279f0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 ** the nul-termi
27a00 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 nator..**.** ^If
27a10 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e pzTail is not N
27a20 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c ULL then *pzTail
27a30 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e is made to poin
27a40 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 t to the first b
27a50 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 yte.** past the
27a60 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 end of the first
27a70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
27a80 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 n zSql. These r
27a90 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 outines only.**
27aa0 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 compile the firs
27ab0 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a t statement in z
27ac0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 Sql, so *pzTail
27ad0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 is left pointing
27ae0 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 to.** what rema
27af0 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a ins uncompiled..
27b00 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 **.** ^*ppStmt i
27b10 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 s left pointing
27b20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 to a compiled [p
27b30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
27b40 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a t] that can be.*
27b50 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 * executed using
27b60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
27b70 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 ]. ^If there is
27b80 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 an error, *ppSt
27b90 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 mt is set.** to
27ba0 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 NULL. ^If the i
27bb0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 nput text contai
27bc0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 ns no SQL (if th
27bd0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d e input is an em
27be0 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 pty.** string or
27bf0 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e a comment) then
27c00 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 *ppStmt is set
27c10 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 to NULL..** The
27c20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 calling procedur
27c30 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 e is responsible
27c40 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 for deleting th
27c50 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 e compiled.** SQ
27c60 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e L statement usin
27c70 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
27c80 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 ize()] after it
27c90 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
27ca0 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 h it..** ppStmt
27cb0 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e may not be NULL.
27cc0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 .**.** ^On succe
27cd0 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f ss, the sqlite3_
27ce0 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 prepare() family
27cf0 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 of routines ret
27d00 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b urn [SQLITE_OK];
27d10 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e .** otherwise an
27d20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
27d30 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
27d40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 The sqlite3_pre
27d50 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 pare_v2() and sq
27d60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
27d70 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 v2() interfaces
27d80 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 are.** recommend
27d90 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 ed for all new p
27da0 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f rograms. The two
27db0 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 older interface
27dc0 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a s are retained.*
27dd0 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 * for backwards
27de0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 compatibility, b
27df0 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 ut their use is
27e00 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 discouraged..**
27e10 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 ^In the "v2" int
27e20 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 erfaces, the pre
27e30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a pared statement.
27e40 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 ** that is retur
27e50 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 ned (the [sqlite
27e60 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 3_stmt] object)
27e70 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 contains a copy
27e80 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e of the.** origin
27e90 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 al SQL text. Thi
27ea0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 s causes the [sq
27eb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e lite3_step()] in
27ec0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 terface to.** be
27ed0 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 have differently
27ee0 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a in three ways:.
27ef0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c **.** <ol>.** <l
27f00 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 i>.** ^If the da
27f10 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 tabase schema ch
27f20 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f anges, instead o
27f30 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c f returning [SQL
27f40 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 ITE_SCHEMA] as i
27f50 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 t.** always used
27f60 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 to do, [sqlite3
27f70 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 _step()] will au
27f80 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f tomatically reco
27f90 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a mpile the SQL.**
27fa0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
27fb0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 ry to run it aga
27fc0 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b in. As many as [
27fd0 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d SQLITE_MAX_SCHEM
27fe0 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 A_RETRY].** retr
27ff0 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 ies will occur b
28000 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 efore sqlite3_st
28010 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e ep() gives up an
28020 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 d returns an err
28030 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a or..** </li>.**.
28040 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e ** <li>.** ^When
28050 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
28060 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
28070 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f )] will return o
28080 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c ne of the detail
28090 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 ed.** [error cod
280a0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 es] or [extended
280b0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 error codes].
280c0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 ^The legacy beha
280d0 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a vior was that.**
280e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
280f0 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 ] would only ret
28100 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 urn a generic [S
28110 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 QLITE_ERROR] res
28120 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 ult code.** and
28130 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
28140 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 would have to ma
28150 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c ke a second call
28160 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
28170 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 et()].** in orde
28180 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e r to find the un
28190 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f derlying cause o
281a0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 f the problem. W
281b0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 ith the "v2" pre
281c0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 pare.** interfac
281d0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 es, the underlyi
281e0 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 ng reason for th
281f0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 e error is retur
28200 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e ned immediately.
28210 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 .** </li>.**.**
28220 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 <li>.** ^If the
28230 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 specific value b
28240 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 ound to [paramet
28250 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 er | host parame
28260 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 ter] in the .**
28270 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 WHERE clause mig
28280 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 ht influence the
28290 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 choice of query
282a0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 plan for a stat
282b0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 ement,.** then t
282c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c he statement wil
282d0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c l be automatical
282e0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 ly recompiled, a
282f0 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 s if there had b
28300 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 een .** a schema
28310 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 change, on the
28320 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f first [sqlite3_
28330 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c step()] call fol
28340 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 lowing any chang
28350 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c e.** to the [sql
28360 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c ite3_bind_text |
28370 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 bindings] of th
28380 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 at [parameter].
28390 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 .** ^The specifi
283a0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 c value of WHERE
283b0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 -clause [paramet
283c0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 er] might influe
283d0 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 nce the .** choi
283e0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e ce of query plan
283f0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
28400 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 r is the left-ha
28410 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 nd side of a [LI
28420 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d KE].** or [GLOB]
28430 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 operator or if
28440 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 the parameter is
28450 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 compared to an
28460 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a indexed column.*
28470 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 * and the [SQLIT
28480 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 E_ENABLE_STAT3]
28490 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
284a0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a ion is enabled..
284b0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c ** </li>.** </ol
284c0 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 >.*/.SQLITE_API
284d0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
284e0 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 LL sqlite3_prepa
284f0 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 re(. sqlite3 *d
28500 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
28510 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
28520 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
28530 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
28540 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
28550 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f UTF-8 encoded */
28560 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
28570 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
28580 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
28590 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
285a0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
285b0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
285c0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
285d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
285e0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 char **pzTail
285f0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
28600 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
28610 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
28620 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
28630 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
28640 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
28650 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
28660 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
28670 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
28680 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
28690 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
286a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
286b0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f UTF-8 encoded */
286c0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
286d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
286e0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
286f0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
28700 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
28710 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
28720 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
28730 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
28740 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 char **pzTail
28750 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
28760 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
28770 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
28780 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
28790 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
287a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
287b0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 6(. sqlite3 *db
287c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
287d0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
287e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
287f0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
28800 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
28810 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
28820 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
28830 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
28840 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
28850 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
28860 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
28870 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
28880 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
28890 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
288a0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
288b0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
288c0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
288d0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
288e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
288f0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
28900 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
28910 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 6_v2(. sqlite3
28920 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
28930 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
28940 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
28950 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 id *zSql,
28960 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
28970 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 , UTF-16 encoded
28980 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
28990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
289a0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
289b0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
289c0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
289d0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
289e0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
289f0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
28a00 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c st void **pzTail
28a10 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
28a20 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
28a30 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
28a40 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
28a50 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 3REF: Retrieving
28a60 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a Statement SQL.*
28a70 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
28a80 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
28a90 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e is interface can
28aa0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 be used to retr
28ab0 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 ieve a saved cop
28ac0 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 y of the origina
28ad0 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 l.** SQL text us
28ae0 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b ed to create a [
28af0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
28b00 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 nt] if that stat
28b10 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d ement was.** com
28b20 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 piled using eith
28b30 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 er [sqlite3_prep
28b40 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 are_v2()] or [sq
28b50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
28b60 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 v2()]..*/.SQLITE
28b70 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
28b80 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
28b90 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 sqlite3_sql(sqli
28ba0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
28bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
28bc0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
28bd0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
28be0 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 Writes The Data
28bf0 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 base.** METHOD:
28c00 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
28c10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
28c20 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 stmt_readonly(X)
28c30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
28c40 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 ns true (non-zer
28c50 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c o) if.** and onl
28c60 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 y if the [prepar
28c70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 ed statement] X
28c80 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 makes no direct
28c90 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 changes to.** th
28ca0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
28cb0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a database file..
28cc0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
28cd0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
28ce0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
28cf0 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 ns] or.** [virtu
28d00 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 al tables] might
28d10 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 change the data
28d20 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 base indirectly
28d30 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 as a side effect
28d40 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 . .** ^(For exa
28d50 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c mple, if an appl
28d60 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 ication defines
28d70 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c a function "eval
28d80 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c ()" that .** cal
28d90 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ls [sqlite3_exec
28da0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f ()], then the fo
28db0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 llowing SQL stat
28dc0 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 ement would.** c
28dd0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
28de0 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 se file through
28df0 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a side-effects:.**
28e00 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
28e10 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 <pre>.** SELE
28e20 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 CT eval('DELETE
28e30 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 FROM t1') FROM t
28e40 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 2;.** </pre></bl
28e50 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
28e60 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 But because the
28e70 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
28e80 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e nt does not chan
28e90 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
28ea0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 file.** directly
28eb0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 , sqlite3_stmt_r
28ec0 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 eadonly() would
28ed0 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 still return tru
28ee0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e e.)^.**.** ^Tran
28ef0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 saction control
28f00 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 statements such
28f10 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d as [BEGIN], [COM
28f20 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d MIT], [ROLLBACK]
28f30 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d ,.** [SAVEPOINT]
28f40 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 , and [RELEASE]
28f50 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 cause sqlite3_st
28f60 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f mt_readonly() to
28f70 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a return true,.**
28f80 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 since the state
28f90 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 ments themselves
28fa0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 do not actually
28fb0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 modify the data
28fc0 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 base but.** rath
28fd0 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 er they control
28fe0 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 the timing of wh
28ff0 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 en other stateme
29000 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a nts modify the .
29010 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 ** database. ^T
29020 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 he [ATTACH] and
29030 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 [DETACH] stateme
29040 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a nts also cause.*
29050 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 * sqlite3_stmt_r
29060 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 eadonly() to ret
29070 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 urn true since,
29080 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 while those stat
29090 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 ements.** change
290a0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
290b0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 on of a database
290c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 connection, the
290d0 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a y do not make .*
290e0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 * changes to the
290f0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
29100 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f database files o
29110 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 n disk..*/.SQLIT
29120 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
29130 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
29140 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 _stmt_readonly(s
29150 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
29160 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
29170 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
29180 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 If A Prepared St
29190 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e atement Has Been
291a0 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 Reset.** METHOD
291b0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
291c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
291d0 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 3_stmt_busy(S) i
291e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
291f0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 true (non-zero)
29200 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 if the.** [prep
29210 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
29220 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 S has been stepp
29230 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 ed at least once
29240 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 using .** [sqli
29250 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 te3_step(S)] but
29260 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 has not run to
29270 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f completion and/o
29280 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 r has not .** be
29290 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b en reset using [
292a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
292b0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 ]. ^The sqlite3
292c0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a _stmt_busy(S).**
292d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
292e0 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 ns false if S is
292f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
29300 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 If S is not a
29310 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 .** NULL pointer
29320 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f and is not a po
29330 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 inter to a valid
29340 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
29350 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c ment].** object,
29360 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
29370 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 or is undefined
29380 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 and probably und
29390 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 esirable..**.**
293a0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 This interface c
293b0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f an be used in co
293c0 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 mbination [sqlit
293d0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a e3_next_stmt()].
293e0 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c ** to locate all
293f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
29400 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 ents associated
29410 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 with a database
29420 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 .** connection t
29430 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 hat are in need
29440 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 of being reset.
29450 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 This can be use
29460 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c d,.** for exampl
29470 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 e, in diagnostic
29480 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 routines to sea
29490 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 rch for prepared
294a0 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 .** statements
294b0 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 that are holding
294c0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f a transaction o
294d0 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 pen..*/.SQLITE_A
294e0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
294f0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 DCALL sqlite3_st
29500 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f mt_busy(sqlite3_
29510 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
29520 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 API3REF: Dynamic
29530 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 ally Typed Value
29540 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f Object.** KEYWO
29550 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 RDS: {protected
29560 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b sqlite3_value} {
29570 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
29580 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a te3_value}.**.**
29590 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 SQLite uses the
295a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
295b0 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 bject to represe
295c0 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a nt all values.**
295d0 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f that can be sto
295e0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 red in a databas
295f0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 e table. SQLite
29600 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 uses dynamic typ
29610 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 ing.** for the v
29620 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e alues it stores.
29630 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 ^Values stored
29640 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 in sqlite3_valu
29650 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e e objects.** can
29660 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c be integers, fl
29670 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
29680 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c ues, strings, BL
29690 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a OBs, or NULL..**
296a0 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 .** An sqlite3_v
296b0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 alue object may
296c0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 be either "prote
296d0 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 cted" or "unprot
296e0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 ected"..** Some
296f0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 interfaces requi
29700 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 re a protected s
29710 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f qlite3_value. O
29720 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a ther interfaces.
29730 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 ** will accept e
29740 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 ither a protecte
29750 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 d or an unprotec
29760 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
29770 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 e..** Every inte
29780 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 rface that accep
29790 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ts sqlite3_value
297a0 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 arguments speci
297b0 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 fies.** whether
297c0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 or not it requir
297d0 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 es a protected s
297e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 qlite3_value. T
297f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 he.** [sqlite3_v
29800 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 alue_dup()] inte
29810 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
29820 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 d to construct a
29830 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 new .** protect
29840 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
29850 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 from an unprote
29860 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
29870 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 ue..**.** The te
29880 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 rms "protected"
29890 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 and "unprotected
298a0 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 " refer to wheth
298b0 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d er or not.** a m
298c0 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 utex is held. A
298d0 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 n internal mutex
298e0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 is held for a p
298f0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
29900 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
29910 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 but no mutex is
29920 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 held for an unp
29930 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
29940 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
29950 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 . If SQLite is
29960 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 compiled to be s
29970 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a ingle-threaded.*
29980 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f * (with [SQLITE_
29990 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e THREADSAFE=0] an
299a0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f d with [sqlite3_
299b0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 threadsafe()] re
299c0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 turning 0).** or
299d0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 if SQLite is ru
299e0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 n in one of redu
299f0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 ced mutex modes
29a00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
29a10 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
29a20 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 or [SQLITE_CONF
29a30 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a IG_MULTITHREAD].
29a40 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 ** then there is
29a50 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 no distinction
29a60 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 between protecte
29a70 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 d and unprotecte
29a80 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
29a90 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 ue objects and t
29aa0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 hey can be used
29ab0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e interchangeably.
29ac0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f However,.** fo
29ad0 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 r maximum code p
29ae0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 ortability it is
29af0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 recommended tha
29b00 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a t applications.*
29b10 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 * still make the
29b20 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
29b30 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 ween protected a
29b40 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a nd unprotected.*
29b50 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
29b60 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 objects even whe
29b70 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 n not strictly r
29b80 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e equired..**.** ^
29b90 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
29ba0 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 e objects that a
29bb0 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 re passed as par
29bc0 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 ameters into the
29bd0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
29be0 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 on of [applicati
29bf0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
29c00 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 unctions] are pr
29c10 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 otected..** ^The
29c20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
29c30 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
29c40 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
29c50 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
29c60 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a unprotected..**
29c70 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c Unprotected sql
29c80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
29c90 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 ts may only be u
29ca0 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c sed with.** [sql
29cb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
29cc0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
29cd0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 3_bind_value()].
29ce0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
29cf0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 _value_blob | sq
29d00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 lite3_value_type
29d10 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a ()] family of.**
29d20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 interfaces requ
29d30 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 ire protected sq
29d40 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
29d50 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 cts..*/.typedef
29d60 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 struct Mem sqlit
29d70 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a e3_value;../*.**
29d80 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 CAPI3REF: SQL F
29d90 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 unction Context
29da0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 Object.**.** The
29db0 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 context in whic
29dc0 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f h an SQL functio
29dd0 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 n executes is st
29de0 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 ored in an.** sq
29df0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 lite3_context ob
29e00 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 ject. ^A pointe
29e10 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f r to an sqlite3_
29e20 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a context object.*
29e30 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 * is always firs
29e40 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b t parameter to [
29e50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
29e60 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
29e70 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 s]..** The appli
29e80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
29e90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c QL function impl
29ea0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 ementation will
29eb0 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 pass this.** poi
29ec0 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 nter through int
29ed0 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 o calls to [sqli
29ee0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c te3_result_int |
29ef0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 sqlite3_result(
29f00 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
29f10 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
29f20 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 t()], [sqlite3_u
29f30 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 ser_data()],.**
29f40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 [sqlite3_context
29f50 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b _db_handle()], [
29f60 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
29f70 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f ata()],.** and/o
29f80 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 r [sqlite3_set_a
29f90 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 uxdata()]..*/.ty
29fa0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
29fb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c ite3_context sql
29fc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f ite3_context;../
29fd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 *.** CAPI3REF: B
29fe0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f inding Values To
29ff0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
2a000 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ents.** KEYWORDS
2a010 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 : {host paramete
2a020 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 r} {host paramet
2a030 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d ers} {host param
2a040 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 eter name}.** KE
2a050 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 YWORDS: {SQL par
2a060 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 ameter} {SQL par
2a070 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 ameters} {parame
2a080 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 ter binding}.**
2a090 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
2a0a0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 stmt.**.** ^(In
2a0b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
2a0c0 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 t text input to
2a0d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2a0e0 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 _v2()] and its v
2a0f0 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 ariants,.** lite
2a100 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c rals may be repl
2a110 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d aced by a [param
2a120 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 eter] that match
2a130 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 es one of follow
2a140 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 ing.** templates
2a150 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
2a160 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 <li> ?.** <li>
2a170 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a ?NNN.** <li> :
2a180 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 VVV.** <li> @VV
2a190 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a V.** <li> $VVV.
2a1a0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </ul>.**.** I
2a1b0 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 n the templates
2a1c0 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 above, NNN repre
2a1d0 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 sents an integer
2a1e0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 literal,.** and
2a1f0 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 VVV represents
2a200 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 an alphanumeric
2a210 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e identifier.)^ ^
2a220 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 The values of th
2a230 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ese.** parameter
2a240 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 s (also called "
2a250 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e host parameter n
2a260 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 ames" or "SQL pa
2a270 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 rameters").** ca
2a280 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 n be set using t
2a290 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
2a2a0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 *() routines def
2a2b0 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a ined here..**.**
2a2c0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
2a2d0 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 ment to the sqli
2a2e0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
2a2f0 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a tines is always.
2a300 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
2a310 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
2a320 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e t] object return
2a330 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 ed from.** [sqli
2a340 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2a350 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
2a360 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 s..**.** ^The se
2a370 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
2a380 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 the index of th
2a390 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 e SQL parameter
2a3a0 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 to be set..** ^T
2a3b0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 he leftmost SQL
2a3c0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e parameter has an
2a3d0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 index of 1. ^W
2a3e0 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d hen the same nam
2a3f0 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 ed.** SQL parame
2a400 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 ter is used more
2a410 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f than once, seco
2a420 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e nd and subsequen
2a430 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 t.** occurrences
2a440 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 have the same i
2a450 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 ndex as the firs
2a460 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a t occurrence..**
2a470 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 ^The index for
2a480 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 named parameters
2a490 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 can be looked u
2a4a0 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b p using the.** [
2a4b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2a4c0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 ameter_index()]
2a4d0 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 API if desired.
2a4e0 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 ^The index.** f
2a4f0 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 or "?NNN" parame
2a500 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 ters is the valu
2a510 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 e of NNN..** ^Th
2a520 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 e NNN value must
2a530 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e be between 1 an
2a540 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c d the [sqlite3_l
2a550 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d imit()].** param
2a560 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d eter [SQLITE_LIM
2a570 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
2a580 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c ER] (default val
2a590 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 ue: 999)..**.**
2a5a0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d ^The third argum
2a5b0 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 ent is the value
2a5c0 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 to bind to the
2a5d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 parameter..** ^I
2a5e0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 f the third para
2a5f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
2a600 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 _bind_text() or
2a610 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2a620 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 t16().** or sqli
2a630 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 te3_bind_blob()
2a640 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
2a650 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 r then the fourt
2a660 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 h parameter.** i
2a670 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 s ignored and th
2a680 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 e end result is
2a690 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 the same as sqli
2a6a0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e te3_bind_null().
2a6b0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 .**.** ^(In thos
2a6c0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 e routines that
2a6d0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 have a fourth ar
2a6e0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 gument, its valu
2a6f0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
2a700 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
2a710 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 he parameter. T
2a720 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 o be clear: the
2a730 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 value is the.**
2a740 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 number of <u>byt
2a750 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 es</u> in the va
2a760 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d lue, not the num
2a770 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
2a780 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 s.)^.** ^If the
2a790 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
2a7a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2a7b0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 _text() or sqlit
2a7c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 e3_bind_text16()
2a7d0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c .** is negative,
2a7e0 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 then the length
2a7f0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 of the string i
2a800 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
2a810 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 of bytes up to t
2a820 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 he first zero te
2a830 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 rminator..** If
2a840 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
2a850 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
2a860 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e bind_blob() is n
2a870 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a egative, then.**
2a880 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
2a890 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 undefined..** I
2a8a0 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 f a non-negative
2a8b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
2a8c0 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f r is provided to
2a8d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
2a8e0 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 xt().** or sqlit
2a8f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 e3_bind_text16()
2a900 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
2a910 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a _text64() then.*
2a920 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 * that parameter
2a930 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 must be the byt
2a940 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 e offset.** wher
2a950 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e e the NUL termin
2a960 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 ator would occur
2a970 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 assuming the st
2a980 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a ring were NUL.**
2a990 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 terminated. If
2a9a0 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 any NUL charact
2a9b0 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 ers occur at byt
2a9c0 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 e offsets less t
2a9d0 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 han .** the valu
2a9e0 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 e of the fourth
2a9f0 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 parameter then t
2aa00 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 he resulting str
2aa10 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a ing value will.*
2aa20 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 * contain embedd
2aa30 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 ed NULs. The re
2aa40 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 sult of expressi
2aa50 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 ons involving st
2aa60 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d rings.** with em
2aa70 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 bedded NULs is u
2aa80 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
2aa90 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d ^The fifth argum
2aaa0 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 ent to the BLOB
2aab0 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 and string bindi
2aac0 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a ng interfaces.**
2aad0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 is a destructor
2aae0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 used to dispose
2aaf0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a of the BLOB or.
2ab00 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 ** string after
2ab10 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 SQLite has finis
2ab20 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 hed with it. ^T
2ab30 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 he destructor is
2ab40 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 called.** to di
2ab50 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f spose of the BLO
2ab60 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e B or string even
2ab70 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 if the call to
2ab80 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a bind API fails..
2ab90 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 ** ^If the fifth
2aba0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 argument is.**
2abb0 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 the special valu
2abc0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 e [SQLITE_STATIC
2abd0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 ], then SQLite a
2abe0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a ssumes that the.
2abf0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 ** information i
2ac00 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d s in static, unm
2ac10 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 anaged space and
2ac20 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
2ac30 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e o be freed..** ^
2ac40 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 If the fifth arg
2ac50 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 ument has the va
2ac60 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e lue [SQLITE_TRAN
2ac70 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 SIENT], then.**
2ac80 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 SQLite makes its
2ac90 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 own private cop
2aca0 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d y of the data im
2acb0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 mediately, befor
2acc0 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 e.** the sqlite3
2acd0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
2ace0 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a e returns..**.**
2acf0 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75 ^The sixth argu
2ad00 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
2ad10 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 bind_text64() mu
2ad20 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 st be one of.**
2ad30 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b [SQLITE_UTF8], [
2ad40 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b SQLITE_UTF16], [
2ad50 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c SQLITE_UTF16BE],
2ad60 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 or [SQLITE_UTF1
2ad70 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 6LE].** to speci
2ad80 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 fy the encoding
2ad90 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 of the text in t
2ada0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
2adb0 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 er. If.** the s
2adc0 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f ixth argument to
2add0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
2ade0 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e xt64() is not on
2adf0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f e of the.** allo
2ae00 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e wed values shown
2ae10 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 above, or if th
2ae20 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 e text encoding
2ae30 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 is different.**
2ae40 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e from the encodin
2ae50 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 g specified by t
2ae60 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 he sixth paramet
2ae70 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 er, then the beh
2ae80 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 avior.** is unde
2ae90 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
2aea0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a e sqlite3_bind_z
2aeb0 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e eroblob() routin
2aec0 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f e binds a BLOB o
2aed0 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a f length N that.
2aee0 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 ** is filled wit
2aef0 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 h zeroes. ^A ze
2af00 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 roblob uses a fi
2af10 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 xed amount of me
2af20 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e mory.** (just an
2af30 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 integer to hold
2af40 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 its size) while
2af50 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f it is being pro
2af60 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 cessed..** Zerob
2af70 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 lobs are intende
2af80 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c d to serve as pl
2af90 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 aceholders for B
2afa0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f LOBs whose.** co
2afb0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 ntent is later w
2afc0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 ritten using.**
2afd0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
2afe0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c en | incremental
2aff0 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 BLOB I/O] routi
2b000 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 nes..** ^A negat
2b010 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 ive value for th
2b020 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c e zeroblob resul
2b030 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e ts in a zero-len
2b040 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 gth BLOB..**.**
2b050 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 ^If any of the s
2b060 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
2b070 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
2b080 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 led with a NULL
2b090 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 pointer.** for t
2b0a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2b0b0 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 tement] or with
2b0c0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
2b0d0 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a ment for which.*
2b0e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
2b0f0 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c )] has been call
2b100 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 ed more recently
2b110 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 than [sqlite3_r
2b120 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e eset()],.** then
2b130 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 the call will r
2b140 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 eturn [SQLITE_MI
2b150 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 SUSE]. If any s
2b160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a qlite3_bind_().*
2b170 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 * routine is pas
2b180 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 sed a [prepared
2b190 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
2b1a0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a has been finaliz
2b1b0 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c ed, the.** resul
2b1c0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 t is undefined a
2b1d0 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d nd probably harm
2b1e0 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 ful..**.** ^Bind
2b1f0 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 ings are not cle
2b200 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c ared by the [sql
2b210 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f ite3_reset()] ro
2b220 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 utine..** ^Unbou
2b230 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 nd parameters ar
2b240 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 e interpreted as
2b250 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 NULL..**.** ^Th
2b260 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
2b270 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2b280 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
2b290 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a success or an.**
2b2a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
2b2b0 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 anything goes w
2b2c0 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 rong..** ^[SQLIT
2b2d0 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 E_TOOBIG] might
2b2e0 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 be returned if t
2b2f0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 he size of a str
2b300 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 ing or BLOB.** e
2b310 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d xceeds limits im
2b320 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 posed by [sqlite
2b330 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 3_limit]([SQLITE
2b340 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 _LIMIT_LENGTH])
2b350 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 or.** [SQLITE_MA
2b360 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b X_LENGTH]..** ^[
2b370 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 SQLITE_RANGE] is
2b380 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 returned if the
2b390 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e parameter.** in
2b3a0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 dex is out of ra
2b3b0 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e nge. ^[SQLITE_N
2b3c0 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 OMEM] is returne
2b3d0 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 d if malloc() fa
2b3e0 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ils..**.** See a
2b3f0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
2b400 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
2b410 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nt()],.** [sqlit
2b420 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2b430 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b r_name()], and [
2b440 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2b450 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
2b460 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2b470 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
2b480 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 L sqlite3_bind_b
2b490 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
2b4a0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f *, int, const vo
2b4b0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 id*, int n, void
2b4c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c (*)(void*));.SQL
2b4d0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
2b4e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2b4f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 e3_bind_blob64(s
2b500 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2b510 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 t, const void*,
2b520 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a sqlite3_uint64,.
2b530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2b540 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 void(*)(
2b550 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f void*));.SQLITE_
2b560 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
2b570 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 TDCALL sqlite3_b
2b580 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 ind_double(sqlit
2b590 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 e3_stmt*, int, d
2b5a0 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 ouble);.SQLITE_A
2b5b0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2b5c0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 DCALL sqlite3_bi
2b5d0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 nd_int(sqlite3_s
2b5e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b tmt*, int, int);
2b5f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2b600 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2b610 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 qlite3_bind_int6
2b620 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
2b630 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e int, sqlite3_in
2b640 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 t64);.SQLITE_API
2b650 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
2b660 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 ALL sqlite3_bind
2b670 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 _null(sqlite3_st
2b680 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 mt*, int);.SQLIT
2b690 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2b6a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2b6b0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 _bind_text(sqlit
2b6c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e e3_stmt*,int,con
2b6d0 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 st char*,int,voi
2b6e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 d(*)(void*));.SQ
2b6f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
2b700 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2b710 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
2b720 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2b730 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c nt, const void*,
2b740 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
2b750 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
2b760 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
2b770 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e CALL sqlite3_bin
2b780 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 d_text64(sqlite3
2b790 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
2b7a0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 st char*, sqlite
2b7b0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 3_uint64,.
2b7c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2b7d0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a void(*)(void*
2b7e0 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 ), unsigned char
2b7f0 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 encoding);.SQLI
2b800 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2b810 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2b820 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 3_bind_value(sql
2b830 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
2b840 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 const sqlite3_v
2b850 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
2b860 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2b870 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 DCALL sqlite3_bi
2b880 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 nd_zeroblob(sqli
2b890 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2b8a0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int n);../*.** C
2b8b0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
2b8c0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 Of SQL Parameter
2b8d0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
2b8e0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2b8f0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 ^This routine ca
2b900 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e n be used to fin
2b910 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
2b920 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d [SQL parameters]
2b930 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 .** in a [prepar
2b940 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 ed statement].
2b950 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 SQL parameters a
2b960 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 re tokens of the
2b970 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f .** form "?", "?
2b980 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 NNN", ":AAA", "$
2b990 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 AAA", or "@AAA"
2b9a0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a that serve as.**
2b9b0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f placeholders fo
2b9c0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 r values that ar
2b9d0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
2b9e0 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a blob | bound].**
2b9f0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 to the paramete
2ba00 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 rs at a later ti
2ba10 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 me..**.** ^(This
2ba20 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c routine actuall
2ba30 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e y returns the in
2ba40 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 dex of the large
2ba50 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a st (rightmost).*
2ba60 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 * parameter. For
2ba70 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 all forms excep
2ba80 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c t ?NNN, this wil
2ba90 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 l correspond to
2baa0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
2bab0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 unique paramete
2bac0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 rs. If paramete
2bad0 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 rs of the ?NNN f
2bae0 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a orm are used,.**
2baf0 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 there may be ga
2bb00 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 ps in the list.)
2bb10 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ^.**.** See also
2bb20 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
2bb30 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
2bb40 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
2bb50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2bb60 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a _name()], and.**
2bb70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
2bb80 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
2bb90 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
2bba0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
2bbb0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 ALL sqlite3_bind
2bbc0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
2bbd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
2bbe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2bbf0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 : Name Of A Host
2bc00 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 Parameter.** ME
2bc10 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2bc20 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 mt.**.** ^The sq
2bc30 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2bc40 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 eter_name(P,N) i
2bc50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2bc60 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 .** the name of
2bc70 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 the N-th [SQL pa
2bc80 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 rameter] in the
2bc90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2bca0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c ent] P..** ^(SQL
2bcb0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 parameters of t
2bcc0 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f he form "?NNN" o
2bcd0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 r ":AAA" or "@AA
2bce0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 A" or "$AAA".**
2bcf0 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 have a name whic
2bd00 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 h is the string
2bd10 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 "?NNN" or ":AAA"
2bd20 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 or "@AAA" or "$
2bd30 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 AAA".** respecti
2bd40 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 vely..** In othe
2bd50 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 r words, the ini
2bd60 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 tial ":" or "$"
2bd70 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a or "@" or "?".**
2bd80 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 is included as
2bd90 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 part of the name
2bda0 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 .)^.** ^Paramete
2bdb0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 rs of the form "
2bdc0 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c ?" without a fol
2bdd0 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 lowing integer h
2bde0 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 ave no name.** a
2bdf0 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 nd are referred
2be00 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 to as "nameless"
2be10 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 or "anonymous p
2be20 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a arameters"..**.*
2be30 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 * ^The first hos
2be40 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 t parameter has
2be50 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e an index of 1, n
2be60 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ot 0..**.** ^If
2be70 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f the value N is o
2be80 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 ut of range or i
2be90 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d f the N-th param
2bea0 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c eter is.** namel
2beb0 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 ess, then NULL i
2bec0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 s returned. ^Th
2bed0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
2bee0 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 g is.** always i
2bef0 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 n UTF-8 encoding
2bf00 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d even if the nam
2bf10 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 ed parameter was
2bf20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 .** originally s
2bf30 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d pecified as UTF-
2bf40 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 16 in [sqlite3_p
2bf50 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a repare16()] or.*
2bf60 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
2bf70 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a re16_v2()]..**.*
2bf80 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
2bf90 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
2bfa0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
2bfb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
2bfc0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
2bfd0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
2bfe0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2bff0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
2c000 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2c010 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 t char *SQLITE_S
2c020 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 TDCALL sqlite3_b
2c030 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
2c040 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
2c050 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , int);../*.** C
2c060 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f API3REF: Index O
2c070 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 f A Parameter Wi
2c080 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a th A Given Name.
2c090 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2c0a0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 e3_stmt.**.** ^R
2c0b0 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 eturn the index
2c0c0 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 of an SQL parame
2c0d0 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 ter given its na
2c0e0 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 me. ^The.** ind
2c0f0 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 ex value returne
2c100 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f d is suitable fo
2c110 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 r use as the sec
2c120 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ond.** parameter
2c130 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e to [sqlite3_bin
2c140 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
2c150 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f ind()]. ^A zero
2c160 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
2c170 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 if no matching p
2c180 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e arameter is foun
2c190 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 d. ^The paramet
2c1a0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 er.** name must
2c1b0 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d be given in UTF-
2c1c0 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 8 even if the or
2c1d0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 iginal statement
2c1e0 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 .** was prepared
2c1f0 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 from UTF-16 tex
2c200 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
2c210 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
2c220 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
2c230 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
2c240 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
2c250 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
2c260 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2c270 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a _count()], and.*
2c280 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2c290 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
2c2a0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
2c2b0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
2c2c0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e CALL sqlite3_bin
2c2d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
2c2e0 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c x(sqlite3_stmt*,
2c2f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
2c300 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 me);../*.** CAPI
2c310 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 3REF: Reset All
2c320 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 Bindings On A Pr
2c330 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
2c340 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
2c350 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
2c360 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 Contrary to the
2c370 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e intuition of man
2c380 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 y, [sqlite3_rese
2c390 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 t()] does not re
2c3a0 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 set.** the [sqli
2c3b0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 te3_bind_blob |
2c3c0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b bindings] on a [
2c3d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2c3e0 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 nt]..** ^Use thi
2c3f0 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 s routine to res
2c400 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 et all host para
2c410 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a meters to NULL..
2c420 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
2c430 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
2c440 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 sqlite3_clear_b
2c450 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f indings(sqlite3_
2c460 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
2c470 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
2c480 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 Of Columns In A
2c490 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 Result Set.** ME
2c4a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2c4b0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e mt.**.** ^Return
2c4c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
2c4d0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 olumns in the re
2c4e0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 sult set returne
2c4f0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 d by the.** [pre
2c500 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2c510 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 . ^This routine
2c520 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 returns 0 if pSt
2c530 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 mt is an SQL.**
2c540 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 statement that d
2c550 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 oes not return d
2c560 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 ata (for example
2c570 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a an [UPDATE])..*
2c580 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2c590 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
2c5a0 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f nt()].*/.SQLITE_
2c5b0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
2c5c0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
2c5d0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 olumn_count(sqli
2c5e0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2c5f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2c600 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 F: Column Names
2c610 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a In A Result Set.
2c620 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2c630 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
2c640 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
2c650 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 turn the name as
2c660 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 signed to a part
2c670 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a icular column.**
2c680 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 in the result s
2c690 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d et of a [SELECT]
2c6a0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 statement. ^Th
2c6b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2c6c0 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 _name().** inter
2c6d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
2c6e0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f ointer to a zero
2c6f0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
2c700 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 8 string.** and
2c710 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
2c720 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 ame16() returns
2c730 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a a pointer to a z
2c740 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
2c750 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e * UTF-16 string.
2c760 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 ^The first par
2c770 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 ameter is the [p
2c780 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2c790 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 t].** that imple
2c7a0 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 ments the [SELEC
2c7b0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 T] statement. ^T
2c7c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
2c7d0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f ter is the.** co
2c7e0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 lumn number. ^T
2c7f0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 he leftmost colu
2c800 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a mn is number 0..
2c810 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 **.** ^The retur
2c820 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 ned string point
2c830 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 er is valid unti
2c840 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 l either the [pr
2c850 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2c860 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 ].** is destroye
2c870 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 d by [sqlite3_fi
2c880 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 nalize()] or unt
2c890 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 il the statement
2c8a0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c is automaticall
2c8b0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 y.** reprepared
2c8c0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c by the first cal
2c8d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
2c8e0 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 ep()] for a part
2c8f0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 icular run.** or
2c900 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 until the next
2c910 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 call to.** sqlit
2c920 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
2c930 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
2c940 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 mn_name16() on t
2c950 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a he same column..
2c960 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 **.** ^If sqlite
2c970 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 3_malloc() fails
2c980 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 during the proc
2c990 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 essing of either
2c9a0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 routine.** (for
2c9b0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 example during
2c9c0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f a conversion fro
2c9d0 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 m UTF-8 to UTF-1
2c9e0 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 6) then a.** NUL
2c9f0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
2ca00 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 urned..**.** ^Th
2ca10 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 e name of a resu
2ca20 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 lt column is the
2ca30 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 value of the "A
2ca40 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a S" clause for.**
2ca50 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 that column, if
2ca60 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 there is an AS
2ca70 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 clause. If ther
2ca80 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 e is no AS claus
2ca90 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 e.** then the na
2caa0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e me of the column
2cab0 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 is unspecified
2cac0 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 and may change f
2cad0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 rom.** one relea
2cae0 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 se of SQLite to
2caf0 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c the next..*/.SQL
2cb00 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
2cb10 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 ar *SQLITE_STDCA
2cb20 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
2cb30 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 n_name(sqlite3_s
2cb40 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 tmt*, int N);.SQ
2cb50 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
2cb60 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 oid *SQLITE_STDC
2cb70 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ALL sqlite3_colu
2cb80 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 mn_name16(sqlite
2cb90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 3_stmt*, int N);
2cba0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2cbb0 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 : Source Of Data
2cbc0 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 In A Query Resu
2cbd0 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 lt.** METHOD: sq
2cbe0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2cbf0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
2cc00 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 provide a means
2cc10 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 to determine th
2cc20 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c e database, tabl
2cc30 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 e, and.** table
2cc40 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 column that is t
2cc50 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 he origin of a p
2cc60 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 articular result
2cc70 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 column in.** [S
2cc80 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
2cc90 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f ..** ^The name o
2cca0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f f the database o
2ccb0 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d r table or colum
2ccc0 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 n can be returne
2ccd0 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 d as.** either a
2cce0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 UTF-8 or UTF-16
2ccf0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f string. ^The _
2cd00 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e database_ routin
2cd10 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 es return.** the
2cd20 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 database name,
2cd30 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 the _table_ rout
2cd40 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 ines return the
2cd50 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a table name, and.
2cd60 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 ** the origin_ r
2cd70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
2cd80 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a he column name..
2cd90 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 ** ^The returned
2cda0 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 string is valid
2cdb0 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 until the [prep
2cdc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2cdd0 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 is destroyed.**
2cde0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
2cdf0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
2ce00 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e til the statemen
2ce10 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c t is automatical
2ce20 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 ly.** reprepared
2ce30 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 by the first ca
2ce40 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
2ce50 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 tep()] for a par
2ce60 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f ticular run.** o
2ce70 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 r until the same
2ce80 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
2ce90 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 requested.** aga
2cea0 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e in in a differen
2ceb0 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a t encoding..**.*
2cec0 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 * ^The names ret
2ced0 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 urned are the or
2cee0 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 iginal un-aliase
2cef0 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a d names of the.*
2cf00 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c * database, tabl
2cf10 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a e, and column..*
2cf20 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
2cf30 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 argument to thes
2cf40 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 e interfaces is
2cf50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2cf60 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 ement]..** ^Thes
2cf70 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
2cf80 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 rn information a
2cf90 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 bout the Nth res
2cfa0 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 ult column retur
2cfb0 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 ned by.** the st
2cfc0 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e atement, where N
2cfd0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 is the second f
2cfe0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 unction argument
2cff0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d ..** ^The left-m
2d000 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f ost column is co
2d010 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 lumn 0 for these
2d020 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
2d030 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c ^If the Nth col
2d040 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 umn returned by
2d050 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
2d060 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f an expression o
2d070 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e r.** subquery an
2d080 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d d is not a colum
2d090 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c n value, then al
2d0a0 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 l of these funct
2d0b0 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e ions return.** N
2d0c0 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 ULL. ^These rou
2d0d0 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 tine might also
2d0e0 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 return NULL if a
2d0f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
2d100 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 on error.** occu
2d110 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c rs. ^Otherwise,
2d120 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 they return the
2d130 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 name of the att
2d140 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 ached database,
2d150 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c table,.** or col
2d160 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 umn that query r
2d170 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 esult column was
2d180 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e extracted from.
2d190 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 .**.** ^As with
2d1a0 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 all other SQLite
2d1b0 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f APIs, those who
2d1c0 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 se names end wit
2d1d0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a h "16" return.**
2d1e0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
2d1f0 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 strings and the
2d200 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 other functions
2d210 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a return UTF-8..**
2d220 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 .** ^These APIs
2d230 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 are only availab
2d240 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 le if the librar
2d250 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 y was compiled w
2d260 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
2d270 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e TE_ENABLE_COLUMN
2d280 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 _METADATA] C-pre
2d290 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c processor symbol
2d2a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f ..**.** If two o
2d2b0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 r more threads c
2d2c0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 all one or more
2d2d0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
2d2e0 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 s against the sa
2d2f0 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 me.** prepared s
2d300 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c tatement and col
2d310 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 umn at the same
2d320 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 time then the re
2d330 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 sults are.** und
2d340 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 efined..**.** If
2d350 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 two or more thr
2d360 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 eads call one or
2d370 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 more.** [sqlite
2d380 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
2d390 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 e_name | column
2d3a0 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 metadata interfa
2d3b0 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ces].** for the
2d3c0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 same [prepared s
2d3d0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 tatement] and re
2d3e0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 sult column.** a
2d3f0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 t the same time
2d400 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 then the results
2d410 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
2d420 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
2d430 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 nst char *SQLITE
2d440 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2d450 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
2d460 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
2d470 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 mt*,int);.SQLITE
2d480 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
2d490 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
2d4a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
2d4b0 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 atabase_name16(s
2d4c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2d4d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
2d4e0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 nst char *SQLITE
2d4f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2d500 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 _column_table_na
2d510 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
2d520 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,int);.SQLITE_AP
2d530 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 I const void *SQ
2d540 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2d550 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c ite3_column_tabl
2d560 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 e_name16(sqlite3
2d570 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c _stmt*,int);.SQL
2d580 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
2d590 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 ar *SQLITE_STDCA
2d5a0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
2d5b0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 n_origin_name(sq
2d5c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2d5d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
2d5e0 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f st void *SQLITE_
2d5f0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
2d600 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
2d610 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
2d620 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t*,int);../*.**
2d630 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 CAPI3REF: Declar
2d640 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 ed Datatype Of A
2d650 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a Query Result.**
2d660 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2d670 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 _stmt.**.** ^(Th
2d680 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
2d690 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 r is a [prepared
2d6a0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
2d6b0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e If this statemen
2d6c0 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 t is a [SELECT]
2d6d0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 statement and th
2d6e0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 e Nth column of
2d6f0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 the.** returned
2d700 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 result set of th
2d710 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 at [SELECT] is a
2d720 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e table column (n
2d730 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 ot an.** express
2d740 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 ion or subquery)
2d750 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 then the declar
2d760 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 ed type of the t
2d770 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 able.** column i
2d780 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e s returned.)^ ^
2d790 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d If the Nth colum
2d7a0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 n of the result
2d7b0 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 set is an.** exp
2d7c0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 ression or subqu
2d7d0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c ery, then a NULL
2d7e0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 pointer is retu
2d7f0 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 rned..** ^The re
2d800 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 turned string is
2d810 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e always UTF-8 en
2d820 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 coded..**.** ^(F
2d830 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 or example, give
2d840 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 n the database s
2d850 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 chema:.**.** CRE
2d860 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 ATE TABLE t1(c1
2d870 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 VARIANT);.**.**
2d880 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e and the followin
2d890 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 g statement to b
2d8a0 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a e compiled:.**.*
2d8b0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c * SELECT c1 + 1,
2d8c0 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a c1 FROM t1;.**.
2d8d0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ** this routine
2d8e0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 would return the
2d8f0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 string "VARIANT
2d900 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 " for the second
2d910 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d result.** colum
2d920 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 n (i==1), and a
2d930 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 NULL pointer for
2d940 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c the first resul
2d950 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e t column (i==0).
2d960 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 )^.**.** ^SQLite
2d970 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 uses dynamic ru
2d980 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 n-time typing.
2d990 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 ^So just because
2d9a0 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 a column.** is
2d9b0 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 declared to cont
2d9c0 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 ain a particular
2d9d0 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d type does not m
2d9e0 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ean that the.**
2d9f0 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 data stored in t
2da00 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 hat column is of
2da10 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 the declared ty
2da20 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a pe. SQLite is.*
2da30 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 * strongly typed
2da40 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 , but the typing
2da50 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 is dynamic not
2da60 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a static. ^Type.*
2da70 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 * is associated
2da80 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 with individual
2da90 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 values, not with
2daa0 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a the containers.
2dab0 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 ** used to hold
2dac0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f those values..*/
2dad0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2dae0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 t char *SQLITE_S
2daf0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
2db00 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 olumn_decltype(s
2db10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2db20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
2db30 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 nst void *SQLITE
2db40 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2db50 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 _column_decltype
2db60 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2db70 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ,int);../*.** CA
2db80 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 PI3REF: Evaluate
2db90 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
2dba0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
2dbb0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2dbc0 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 After a [prepare
2dbd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 d statement] has
2dbe0 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 been prepared u
2dbf0 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b sing either.** [
2dc00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2dc10 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
2dc20 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
2dc30 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 ] or one of the
2dc40 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 legacy.** interf
2dc50 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 aces [sqlite3_pr
2dc60 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c epare()] or [sql
2dc70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
2dc80 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e ], this function
2dc90 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c .** must be call
2dca0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 ed one or more t
2dcb0 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 imes to evaluate
2dcc0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a the statement..
2dcd0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c **.** The detail
2dce0 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f s of the behavio
2dcf0 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 r of the sqlite3
2dd00 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 _step() interfac
2dd10 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 e depend.** on w
2dd20 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 hether the state
2dd30 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 ment was prepare
2dd40 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 d using the newe
2dd50 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 r "v2" interface
2dd60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
2dd70 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
2dd80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2dd90 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6_v2()] or the o
2dda0 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 lder legacy.** i
2ddb0 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 nterface [sqlite
2ddc0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 3_prepare()] and
2ddd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2dde0 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 e16()]. The use
2ddf0 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 of the.** new "
2de00 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 v2" interface is
2de10 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 recommended for
2de20 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e new application
2de30 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 s but the legacy
2de40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 .** interface wi
2de50 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 ll continue to b
2de60 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a e supported..**.
2de70 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 ** ^In the legac
2de80 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 y interface, the
2de90 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 return value wi
2dea0 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 ll be either [SQ
2deb0 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b LITE_BUSY],.** [
2dec0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 SQLITE_DONE], [S
2ded0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c QLITE_ROW], [SQL
2dee0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b ITE_ERROR], or [
2def0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a SQLITE_MISUSE]..
2df00 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 ** ^With the "v2
2df10 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 " interface, any
2df20 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 of the other [r
2df30 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a esult codes] or.
2df40 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
2df50 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 ult codes] might
2df60 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 be returned as
2df70 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 well..**.** ^[SQ
2df80 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 LITE_BUSY] means
2df90 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 that the databa
2dfa0 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e se engine was un
2dfb0 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 able to acquire
2dfc0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
2dfd0 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 locks it needs t
2dfe0 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e o do its job. ^
2dff0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 If the statement
2e000 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a is a [COMMIT].*
2e010 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 * or occurs outs
2e020 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 ide of an explic
2e030 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 it transaction,
2e040 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 then you can ret
2e050 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d ry the.** statem
2e060 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 ent. If the sta
2e070 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 tement is not a
2e080 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 [COMMIT] and occ
2e090 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a urs within an.**
2e0a0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
2e0b0 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 ction then you s
2e0c0 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 hould rollback t
2e0d0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 he transaction b
2e0e0 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 efore.** continu
2e0f0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c ing..**.** ^[SQL
2e100 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 ITE_DONE] means
2e110 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 that the stateme
2e120 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 nt has finished
2e130 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 executing.** suc
2e140 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 cessfully. sqli
2e150 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c te3_step() shoul
2e160 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 d not be called
2e170 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 again on this vi
2e180 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 rtual.** machine
2e190 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 without first c
2e1a0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
2e1b0 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 reset()] to rese
2e1c0 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a t the virtual.**
2e1d0 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f machine back to
2e1e0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 its initial sta
2e1f0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 te..**.** ^If th
2e200 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
2e210 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 being executed r
2e220 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c eturns any data,
2e230 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f then [SQLITE_RO
2e240 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 W].** is returne
2e250 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 d each time a ne
2e260 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 w row of data is
2e270 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 ready for proce
2e280 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 ssing by the.**
2e290 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 caller. The valu
2e2a0 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 es may be access
2e2b0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f ed using the [co
2e2c0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 lumn access func
2e2d0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 tions]..** sqlit
2e2e0 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c e3_step() is cal
2e2f0 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 led again to ret
2e300 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 rieve the next r
2e310 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a ow of data..**.*
2e320 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 * ^[SQLITE_ERROR
2e330 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 ] means that a r
2e340 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 un-time error (s
2e350 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 uch as a constra
2e360 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e int.** violation
2e370 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 ) has occurred.
2e380 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
2e390 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 should not be ca
2e3a0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a lled again on.**
2e3b0 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e the VM. More in
2e3c0 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 formation may be
2e3d0 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e found by callin
2e3e0 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 g [sqlite3_errms
2e3f0 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 g()]..** ^With t
2e400 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
2e410 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 ace, a more spec
2e420 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 ific error code
2e430 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a (for example,.**
2e440 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
2e450 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 PT], [SQLITE_SCH
2e460 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f EMA], [SQLITE_CO
2e470 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 RRUPT], and so f
2e480 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 orth).** can be
2e490 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c obtained by call
2e4a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
2e4b0 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 et()] on the.**
2e4c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2e4d0 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 ent]. ^In the "
2e4e0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a v2" interface,.*
2e4f0 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 * the more speci
2e500 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 fic error code i
2e510 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 s returned direc
2e520 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 tly by sqlite3_s
2e530 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 tep()..**.** [SQ
2e540 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 LITE_MISUSE] mea
2e550 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 ns that the this
2e560 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c routine was cal
2e570 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 led inappropriat
2e580 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 ely..** Perhaps
2e590 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e it was called on
2e5a0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2e5b0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 tement] that has
2e5c0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e .** already been
2e5d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2e5e0 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 ze | finalized]
2e5f0 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 or on one that h
2e600 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 ad.** previously
2e610 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
2e620 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c E_ERROR] or [SQL
2e630 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 ITE_DONE]. Or i
2e640 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 t could.** be th
2e650 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 e case that the
2e660 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
2e670 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e nnection is bein
2e680 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 g used by two or
2e690 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 .** more threads
2e6a0 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d at the same mom
2e6b0 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a ent in time..**.
2e6c0 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 ** For all versi
2e6d0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 ons of SQLite up
2e6e0 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e to and includin
2e6f0 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 g 3.6.23.1, a ca
2e700 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
2e710 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 3_reset()] was r
2e720 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71 equired after sq
2e730 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 lite3_step() ret
2e740 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a urned anything.*
2e750 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 * other than [SQ
2e760 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 LITE_ROW] before
2e770 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 any subsequent
2e780 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a invocation of.**
2e790 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e sqlite3_step().
2e7a0 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 Failure to res
2e7b0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 et the prepared
2e7c0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 statement using
2e7d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
2e7e0 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 et()] would resu
2e7f0 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 lt in an [SQLITE
2e800 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 _MISUSE] return
2e810 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f from.** sqlite3_
2e820 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 step(). But aft
2e830 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 er version 3.6.2
2e840 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 3.1, sqlite3_ste
2e850 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c p() began.** cal
2e860 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 ling [sqlite3_re
2e870 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 set()] automatic
2e880 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 ally in this cir
2e890 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 cumstance rather
2e8a0 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 .** than returni
2e8b0 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 ng [SQLITE_MISUS
2e8c0 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 E]. This is not
2e8d0 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f considered a co
2e8e0 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 mpatibility.** b
2e8f0 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 reak because any
2e900 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 application tha
2e910 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20 t ever receives
2e920 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 an SQLITE_MISUSE
2e930 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f error.** is bro
2e940 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f ken by definitio
2e950 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f n. The [SQLITE_
2e960 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 OMIT_AUTORESET]
2e970 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
2e980 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 ion.** can be us
2e990 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 ed to restore th
2e9a0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f e legacy behavio
2e9b0 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 r..**.** <b>Goof
2e9c0 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 y Interface Aler
2e9d0 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 t:</b> In the le
2e9e0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
2e9f0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 the sqlite3_step
2ea00 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 ().** API always
2ea10 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 returns a gener
2ea20 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b ic error code, [
2ea30 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 SQLITE_ERROR], f
2ea40 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 ollowing any.**
2ea50 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e error other than
2ea60 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 [SQLITE_BUSY] a
2ea70 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 nd [SQLITE_MISUS
2ea80 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 E]. You must ca
2ea90 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 ll.** [sqlite3_r
2eaa0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 eset()] or [sqli
2eab0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2eac0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 in order to find
2ead0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 one of the.** s
2eae0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 pecific [error c
2eaf0 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 odes] that bette
2eb00 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 r describes the
2eb10 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d error..** We adm
2eb20 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 it that this is
2eb30 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 a goofy design.
2eb40 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 The problem has
2eb50 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 been fixed.** w
2eb60 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 ith the "v2" int
2eb70 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 erface. If you
2eb80 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 prepare all of y
2eb90 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e our SQL statemen
2eba0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 ts.** using eith
2ebb0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 er [sqlite3_prep
2ebc0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 are_v2()] or [sq
2ebd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2ebe0 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a v2()] instead.**
2ebf0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b of the legacy [
2ec00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
2ec10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
2ec20 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 prepare16()] int
2ec30 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e erfaces,.** then
2ec40 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 the more specif
2ec50 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ic [error codes]
2ec60 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 are returned di
2ec70 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c rectly.** by sql
2ec80 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 ite3_step(). Th
2ec90 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 e use of the "v2
2eca0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
2ecb0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 ecommended..*/.S
2ecc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2ecd0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2ece0 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 ite3_step(sqlite
2ecf0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
2ed00 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
2ed10 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
2ed20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 a result set.**
2ed30 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
2ed40 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 stmt.**.** ^The
2ed50 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
2ed60 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 nt(P) interface
2ed70 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
2ed80 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
2ed90 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 the.** current
2eda0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c row of the resul
2edb0 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 t set of [prepar
2edc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e ed statement] P.
2edd0 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 .** ^If prepared
2ede0 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 statement P doe
2edf0 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c s not have resul
2ee00 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 ts ready to retu
2ee10 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 rn.** (via calls
2ee20 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
2ee30 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 _column_int | sq
2ee40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 lite3_column_*()
2ee50 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 ] of.** interfac
2ee60 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 es) then sqlite3
2ee70 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 _data_count(P) r
2ee80 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 eturns 0..** ^Th
2ee90 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
2eea0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 ount(P) routine
2eeb0 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 also returns 0 i
2eec0 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f P is a NULL po
2eed0 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 inter..** ^The s
2eee0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2eef0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 t(P) routine ret
2ef00 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 urns 0 if the pr
2ef10 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a evious call to.*
2ef20 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d * [sqlite3_step]
2ef30 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 (P) returned [SQ
2ef40 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 LITE_DONE]. ^Th
2ef50 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
2ef60 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 ount(P).** will
2ef70 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 return non-zero
2ef80 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c if previous call
2ef90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
2efa0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a p](P) returned.*
2efb0 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 * [SQLITE_ROW],
2efc0 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 except in the ca
2efd0 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d se of the [PRAGM
2efe0 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 A incremental_va
2eff0 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 cuum].** where i
2f000 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 t always returns
2f010 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 zero since each
2f020 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 step of that mu
2f030 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 lti-step.** prag
2f040 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c ma returns 0 col
2f050 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a umns of data..**
2f060 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
2f070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
2f080 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 unt()].*/.SQLITE
2f090 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
2f0a0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
2f0b0 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 data_count(sqlit
2f0c0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
2f0d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2f0e0 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 : Fundamental Da
2f0f0 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f tatypes.** KEYWO
2f100 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 RDS: SQLITE_TEXT
2f110 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 .**.** ^(Every v
2f120 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 alue in SQLite h
2f130 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 as one of five f
2f140 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 undamental datat
2f150 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ypes:.**.** <ul>
2f160 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 .** <li> 64-bit
2f170 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a signed integer.*
2f180 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 * <li> 64-bit IE
2f190 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e EE floating poin
2f1a0 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e t number.** <li>
2f1b0 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 string.** <li>
2f1c0 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c BLOB.** <li> NUL
2f1d0 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a L.** </ul>)^.**.
2f1e0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
2f1f0 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 ts are codes for
2f200 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 each of those t
2f210 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 ypes..**.** Note
2f220 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 that the SQLITE
2f230 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 _TEXT constant w
2f240 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 as also used in
2f250 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 SQLite version 2
2f260 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 .** for a comple
2f270 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d tely different m
2f280 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 eaning. Softwar
2f290 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 e that links aga
2f2a0 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c inst both.** SQL
2f2b0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e ite version 2 an
2f2c0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e d SQLite version
2f2d0 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 3 should use SQ
2f2e0 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a LITE3_TEXT, not.
2f2f0 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a ** SQLITE_TEXT..
2f300 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
2f310 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 E_INTEGER 1.#de
2f320 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 fine SQLITE_FLOA
2f330 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 T 2.#define S
2f340 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 QLITE_BLOB 4
2f350 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2f360 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 NULL 5.#ifde
2f370 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 f SQLITE_TEXT.#
2f380 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 undef SQLITE_TEX
2f390 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 T.#else.# define
2f3a0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 SQLITE_TEXT
2f3b0 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 3.#endif.#defin
2f3c0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 e SQLITE3_TEXT
2f3d0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3../*.** CAPI
2f3e0 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 3REF: Result Val
2f3f0 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 ues From A Query
2f400 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 .** KEYWORDS: {c
2f410 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e olumn access fun
2f420 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f ctions}.** METHO
2f430 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
2f440 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
2f450 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 tines return inf
2f460 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 ormation about a
2f470 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f single column o
2f480 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a f the current.**
2f490 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 result row of a
2f4a0 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 query. ^In eve
2f4b0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 ry case the firs
2f4c0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 t argument is a
2f4d0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 pointer.** to th
2f4e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2f4f0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 ement] that is b
2f500 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 eing evaluated (
2f510 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
2f520 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 t*].** that was
2f530 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 returned from [s
2f540 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2f550 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 2()] or one of i
2f560 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 ts variants).**
2f570 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 and the second a
2f580 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 rgument is the i
2f590 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 ndex of the colu
2f5a0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 mn for which inf
2f5b0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 ormation.** shou
2f5c0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 ld be returned.
2f5d0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f ^The leftmost co
2f5e0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
2f5f0 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 lt set has the i
2f600 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 ndex 0..** ^The
2f610 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
2f620 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 s in the result
2f630 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 can be determine
2f640 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 d using.** [sqli
2f650 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 te3_column_count
2f660 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ()]..**.** If th
2f670 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
2f680 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 does not current
2f690 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 ly point to a va
2f6a0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 lid row, or if t
2f6b0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 he.** column ind
2f6c0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e ex is out of ran
2f6d0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 ge, the result i
2f6e0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 s undefined..**
2f6f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d These routines m
2f700 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 ay only be calle
2f710 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 d when the most
2f720 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a recent call to.*
2f730 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
2f740 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 )] has returned
2f750 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 [SQLITE_ROW] and
2f760 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c neither.** [sql
2f770 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f ite3_reset()] no
2f780 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
2f790 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e ize()] have been
2f7a0 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 called subseque
2f7b0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 ntly..** If any
2f7c0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
2f7d0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 s are called aft
2f7e0 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 er [sqlite3_rese
2f7f0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 t()] or.** [sqli
2f800 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2f810 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 or after [sqlite
2f820 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 3_step()] has re
2f830 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 turned.** someth
2f840 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ing other than [
2f850 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 SQLITE_ROW], the
2f860 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
2f870 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 efined..** If [s
2f880 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
2f890 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
2f8a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2f8b0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 finalize()].** a
2f8c0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 re called from a
2f8d0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
2f8e0 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 d while any of t
2f8f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a hese routines.**
2f900 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 are pending, th
2f910 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 en the results a
2f920 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a re undefined..**
2f930 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2f940 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 _column_type() r
2f950 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
2f960 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e he.** [SQLITE_IN
2f970 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 TEGER | datatype
2f980 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 code] for the i
2f990 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 nitial data type
2f9a0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c .** of the resul
2f9b0 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 t column. ^The
2f9c0 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 returned value i
2f9d0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 s one of [SQLITE
2f9e0 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 _INTEGER],.** [S
2f9f0 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 QLITE_FLOAT], [S
2fa00 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 QLITE_TEXT], [SQ
2fa10 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b LITE_BLOB], or [
2fa20 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 SQLITE_NULL]. T
2fa30 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 he value.** retu
2fa40 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
2fa50 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 column_type() is
2fa60 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c only meaningful
2fa70 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 if no type.** c
2fa80 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 onversions have
2fa90 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 occurred as desc
2faa0 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 ribed below. Af
2fab0 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 ter a type conve
2fac0 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 rsion,.** the va
2fad0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
2fae0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2faf0 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e ype() is undefin
2fb00 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 ed. Future.** v
2fb10 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
2fb20 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 e may change the
2fb30 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c behavior of sql
2fb40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
2fb50 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ().** following
2fb60 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f a type conversio
2fb70 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 n..**.** ^If the
2fb80 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f result is a BLO
2fb90 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e B or UTF-8 strin
2fba0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 g then the sqlit
2fbb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2fbc0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
2fbd0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
2fbe0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2fbf0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e BLOB or string.
2fc00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2fc10 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 lt is a UTF-16 s
2fc20 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 tring, then sqli
2fc30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2fc40 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 () converts.** t
2fc50 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 he string to UTF
2fc60 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 -8 and then retu
2fc70 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2fc80 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 f bytes..** ^If
2fc90 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2fca0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 numeric value th
2fcb0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2fcc0 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a n_bytes() uses.*
2fcd0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 * [sqlite3_snpri
2fce0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 ntf()] to conver
2fcf0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 t that value to
2fd00 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 a UTF-8 string a
2fd10 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 nd returns.** th
2fd20 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
2fd30 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 s in that string
2fd40 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
2fd50 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 ult is NULL, the
2fd60 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
2fd70 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 _bytes() returns
2fd80 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 zero..**.** ^If
2fd90 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
2fda0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 BLOB or UTF-16
2fdb0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 string then the
2fdc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2fdd0 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 ytes16().** rout
2fde0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
2fdf0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2fe00 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
2fe10 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
2fe20 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
2fe30 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 TF-8 string, the
2fe40 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
2fe50 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 _bytes16() conve
2fe60 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e rts.** the strin
2fe70 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 g to UTF-16 and
2fe80 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 then returns the
2fe90 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2fea0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
2feb0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 ult is a numeric
2fec0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 value then sqli
2fed0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2fee0 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 16() uses.** [sq
2fef0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
2ff00 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 ] to convert tha
2ff10 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 t value to a UTF
2ff20 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 -16 string and r
2ff30 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 eturns.** the nu
2ff40 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
2ff50 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a that string..**
2ff60 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
2ff70 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 is NULL, then sq
2ff80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2ff90 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a es16() returns z
2ffa0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ero..**.** ^The
2ffb0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 values returned
2ffc0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by [sqlite3_colu
2ffd0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 mn_bytes()] and
2ffe0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
2fff0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 umn_bytes16()] d
30000 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 o not include th
30010 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
30020 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a rs at the end.**
30030 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 of the string.
30040 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 ^For clarity: t
30050 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e he values return
30060 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 ed by.** [sqlite
30070 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
30080 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
30090 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d olumn_bytes16()]
300a0 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 are the number
300b0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 of.** bytes in t
300c0 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 he string, not t
300d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 he number of cha
300e0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e racters..**.** ^
300f0 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 Strings returned
30100 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
30110 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 mn_text() and sq
30120 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
30130 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 t16(),.** even e
30140 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 mpty strings, ar
30150 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 e always zero-te
30160 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 rminated. ^The
30170 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 return.** value
30180 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c from sqlite3_col
30190 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 umn_blob() for a
301a0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f zero-length BLO
301b0 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e B is a NULL poin
301c0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 ter..**.** <b>Wa
301d0 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 rning:</b> ^The
301e0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
301f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by [sqlite3_colu
30200 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 mn_value()] is a
30210 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 n.** [unprotecte
30220 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
30230 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d object. In a m
30240 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 ultithreaded env
30250 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 ironment,.** an
30260 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
30270 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
30280 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 may only be use
30290 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a d safely with.**
302a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 [sqlite3_bind_v
302b0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c alue()] and [sql
302c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
302d0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 e()]..** If the
302e0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
302f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
30300 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ct returned by.*
30310 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
30320 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 n_value()] is us
30330 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 ed in any other
30340 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 way, including c
30350 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 alls.** to routi
30360 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 nes like [sqlite
30370 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 3_value_int()],
30380 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
30390 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 ext()],.** or [s
303a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
303b0 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 es()], the behav
303c0 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 ior is not threa
303d0 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 dsafe..**.** The
303e0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 se routines atte
303f0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 mpt to convert t
30400 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 he value where a
30410 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f ppropriate. ^Fo
30420 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 r.** example, if
30430 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 the internal re
30440 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 presentation is
30450 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 FLOAT and a text
30460 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 result.** is re
30470 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 quested, [sqlite
30480 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 3_snprintf()] is
30490 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 used internally
304a0 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a to perform the.
304b0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 ** conversion au
304c0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 tomatically. ^(
304d0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 The following ta
304e0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 ble details the
304f0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 conversions.** t
30500 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a hat are applied:
30510 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
30520 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f te>.** <table bo
30530 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 rder="1">.** <tr
30540 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 ><th> Internal<b
30550 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 r>Type <th> Requ
30560 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 ested<br>Type <t
30570 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a h> Conversion.*
30580 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e *.** <tr><td> N
30590 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 ULL <td> INTE
305a0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c GER <td> Resul
305b0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 t is 0.** <tr><t
305c0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
305d0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
305e0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a Result is 0.0.**
305f0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
30600 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
30610 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
30620 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
30630 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
30640 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 L <td> BLOB
30650 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 <td> Result
30660 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
30670 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e r.** <tr><td> IN
30680 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f TEGER <td> FLO
30690 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 AT <td> Conve
306a0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 rt from integer
306b0 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e to float.** <tr>
306c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
306d0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
306e0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e > ASCII renderin
306f0 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 g of the integer
30700 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 .** <tr><td> INT
30710 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f EGER <td> BLO
30720 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 B <td> Same a
30730 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a s INTEGER->TEXT.
30740 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f ** <tr><td> FLO
30750 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 AT <td> INTEGE
30760 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 R <td> [CAST]
30770 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 to INTEGER.** <t
30780 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 r><td> FLOAT
30790 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
307a0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 td> ASCII render
307b0 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 ing of the float
307c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
307d0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f OAT <td> BLO
307e0 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d B <td> [CAST]
307f0 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e to BLOB.** <tr>
30800 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
30810 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
30820 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 > [CAST] to INTE
30830 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 GER.** <tr><td>
30840 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 TEXT <td> F
30850 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 LOAT <td> [CA
30860 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c ST] to REAL.** <
30870 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 tr><td> TEXT
30880 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
30890 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a <td> No change.*
308a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
308b0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
308c0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 <td> [CAST] t
308d0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 o INTEGER.** <tr
308e0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c ><td> BLOB <
308f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
30900 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 d> [CAST] to REA
30910 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 L.** <tr><td> B
30920 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 LOB <td> TE
30930 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 XT <td> Add a
30940 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
30950 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f if needed.** </
30960 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 table>.** </bloc
30970 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 kquote>)^.**.**
30980 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 Note that when t
30990 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 ype conversions
309a0 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 occur, pointers
309b0 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f returned by prio
309c0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 r.** calls to sq
309d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
309e0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c b(), sqlite3_col
309f0 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f umn_text(), and/
30a00 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
30a10 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 lumn_text16() ma
30a20 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 y be invalidated
30a30 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 ..** Type conver
30a40 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 sions and pointe
30a50 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 r invalidations
30a60 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 might occur.** i
30a70 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 n the following
30a80 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c cases:.**.** <ul
30a90 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e >.** <li> The in
30aa0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 itial content is
30ab0 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 a BLOB and sqli
30ac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
30ad0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c ) or.** sql
30ae0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
30af0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 16() is called.
30b00 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 A zero-terminat
30b10 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 or might.**
30b20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 need to be adde
30b30 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e d to the string.
30b40 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 </li>.** <li> Th
30b50 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
30b60 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 t is UTF-8 text
30b70 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
30b80 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a mn_bytes16() or.
30b90 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f ** sqlite3_
30ba0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
30bb0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 is called. The
30bc0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 content must be
30bd0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 converted.**
30be0 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 to UTF-16.</li
30bf0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e >.** <li> The in
30c00 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 itial content is
30c10 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 UTF-16 text and
30c20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30c30 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 bytes() or.**
30c40 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
30c50 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c n_text() is call
30c60 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 ed. The content
30c70 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 must be convert
30c80 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 ed.** to UT
30c90 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 F-8.</li>.** </u
30ca0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 l>.**.** ^Conver
30cb0 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 sions between UT
30cc0 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 F-16be and UTF-1
30cd0 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6le are always d
30ce0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 one in place and
30cf0 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c do.** not inval
30d00 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f idate a prior po
30d10 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 inter, though of
30d20 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 course the cont
30d30 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 ent of the buffe
30d40 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 r.** that the pr
30d50 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 ior pointer refe
30d60 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 rences will have
30d70 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 been modified.
30d80 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 Other kinds.**
30d90 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 of conversion ar
30da0 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 e done in place
30db0 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 when it is possi
30dc0 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d ble, but sometim
30dd0 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e es they.** are n
30de0 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 ot possible and
30df0 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 in those cases p
30e00 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 rior pointers ar
30e10 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a e invalidated..*
30e20 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 *.** The safest
30e30 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 policy is to inv
30e40 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e oke these routin
30e50 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 es.** in one of
30e60 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 the following wa
30e70 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a ys:.**.** <ul>.*
30e80 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
30e90 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c olumn_text() fol
30ea0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
30eb0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c _column_bytes()<
30ec0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c /li>.** <li>sql
30ed0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
30ee0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 () followed by s
30ef0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
30f00 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c tes()</li>.** <
30f10 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d li>sqlite3_colum
30f20 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f n_text16() follo
30f30 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 wed by sqlite3_c
30f40 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c olumn_bytes16()<
30f50 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a /li>.** </ul>.**
30f60 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 .** In other wor
30f70 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 ds, you should c
30f80 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 all sqlite3_colu
30f90 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 mn_text(),.** sq
30fa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
30fb0 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f b(), or sqlite3_
30fc0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
30fd0 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 first to force t
30fe0 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 he result.** int
30ff0 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f o the desired fo
31000 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b rmat, then invok
31010 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
31020 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 _bytes() or.** s
31030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
31040 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 tes16() to find
31050 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
31060 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 result. Do not
31070 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 mix calls.** to
31080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
31090 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ext() or sqlite3
310a0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 _column_blob() w
310b0 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 ith calls to.**
310c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
310d0 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f ytes16(), and do
310e0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 not mix calls t
310f0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
31100 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 _text16().** wit
31110 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 h calls to sqlit
31120 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
31130 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f )..**.** ^The po
31140 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 inters returned
31150 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 are valid until
31160 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f a type conversio
31170 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 n occurs as.** d
31180 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 escribed above,
31190 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 or until [sqlite
311a0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 3_step()] or [sq
311b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
311c0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 r.** [sqlite3_fi
311d0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c nalize()] is cal
311e0 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 led. ^The memor
311f0 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 y space used to
31200 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 hold strings.**
31210 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 and BLOBs is fre
31220 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
31230 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 . Do <em>not</e
31240 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e m> pass the poin
31250 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a ters returned.**
31260 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 from [sqlite3_c
31270 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b olumn_blob()], [
31280 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
31290 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 ext()], etc. int
312a0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 o.** [sqlite3_fr
312b0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 ee()]..**.** ^(I
312c0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
312d0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 ation error occu
312e0 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 rs during the ev
312f0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a aluation of any.
31300 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ** of these rout
31310 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 ines, a default
31320 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 value is returne
31330 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 d. The default
31340 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 value.** is eith
31350 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 er the integer 0
31360 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 , the floating p
31370 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c oint number 0.0,
31380 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f or a NULL.** po
31390 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 inter. Subseque
313a0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c nt calls to [sql
313b0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 ite3_errcode()]
313c0 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b will return.** [
313d0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e SQLITE_NOMEM].)^
313e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 .*/.SQLITE_API c
313f0 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 onst void *SQLIT
31400 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
31410 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 3_column_blob(sq
31420 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
31430 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
31440 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
31450 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f DCALL sqlite3_co
31460 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 lumn_bytes(sqlit
31470 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
31480 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
31490 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
314a0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
314b0 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 n_bytes16(sqlite
314c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
314d0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 l);.SQLITE_API d
314e0 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44 ouble SQLITE_STD
314f0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
31500 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 umn_double(sqlit
31510 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
31520 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
31530 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
31540 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
31550 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 n_int(sqlite3_st
31560 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
31570 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
31580 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f e3_int64 SQLITE_
31590 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
315a0 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c column_int64(sql
315b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
315c0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
315d0 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 I const unsigned
315e0 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 char *SQLITE_ST
315f0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f DCALL sqlite3_co
31600 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 lumn_text(sqlite
31610 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
31620 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 l);.SQLITE_API c
31630 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 onst void *SQLIT
31640 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
31650 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
31660 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
31670 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
31680 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
31690 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
316a0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 column_type(sqli
316b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
316c0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
316d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a sqlite3_value *
316e0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
316f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
31700 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lue(sqlite3_stmt
31710 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f *, int iCol);../
31720 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
31730 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 estroy A Prepare
31740 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 d Statement Obje
31750 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 ct.** DESTRUCTOR
31760 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
31770 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
31780 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 3_finalize() fun
31790 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 ction is called
317a0 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 to delete a [pre
317b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
317c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 ..** ^If the mos
317d0 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 t recent evaluat
317e0 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 ion of the state
317f0 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 ment encountered
31800 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 no errors.** or
31810 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e if the statemen
31820 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 t is never been
31830 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 evaluated, then
31840 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
31850 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 () returns.** SQ
31860 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 LITE_OK. ^If th
31870 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 e most recent ev
31880 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 aluation of stat
31890 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 ement S failed,
318a0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f then.** sqlite3_
318b0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 finalize(S) retu
318c0 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 rns the appropri
318d0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ate [error code]
318e0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 or.** [extended
318f0 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a error code]..**
31900 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
31910 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 _finalize(S) rou
31920 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c tine can be call
31930 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 ed at any point
31940 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 during.** the li
31950 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 fe cycle of [pre
31960 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
31970 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 S:.** before st
31980 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 atement S is eve
31990 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 r evaluated, aft
319a0 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 er.** one or mor
319b0 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 e calls to [sqli
319c0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 te3_reset()], or
319d0 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a after any call.
319e0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ** to [sqlite3_s
319f0 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 tep()] regardles
31a00 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
31a10 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e not the statemen
31a20 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 t has.** complet
31a30 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a ed execution..**
31a40 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 .** ^Invoking sq
31a50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
31a60 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 on a NULL point
31a70 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 er is a harmless
31a80 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 no-op..**.** Th
31a90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
31aa0 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 st finalize ever
31ab0 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 y [prepared stat
31ac0 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 ement] in order
31ad0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f to avoid.** reso
31ae0 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 urce leaks. It
31af0 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 is a grievous er
31b00 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c ror for the appl
31b10 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 ication to try t
31b20 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 o use.** a prepa
31b30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 red statement af
31b40 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 ter it has been
31b50 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 finalized. Any
31b60 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 use of a prepare
31b70 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 d.** statement a
31b80 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e fter it has been
31b90 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 finalized can r
31ba0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e esult in undefin
31bb0 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 ed and.** undesi
31bc0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 rable behavior s
31bd0 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 uch as segfaults
31be0 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 and heap corrup
31bf0 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f tion..*/.SQLITE_
31c00 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
31c10 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 TDCALL sqlite3_f
31c20 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f inalize(sqlite3_
31c30 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
31c40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
31c50 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 eset A Prepared
31c60 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
31c70 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
31c80 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 te3_stmt.**.** T
31c90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 he sqlite3_reset
31ca0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 () function is c
31cb0 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 alled to reset a
31cc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
31cd0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 ment].** object
31ce0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 back to its init
31cf0 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 ial state, ready
31d00 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 to be re-execut
31d10 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 ed..** ^Any SQL
31d20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 statement variab
31d30 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c les that had val
31d40 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 ues bound to the
31d50 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b m using.** the [
31d60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
31d70 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 b | sqlite3_bind
31d80 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e _*() API] retain
31d90 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a their values..*
31da0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 * Use [sqlite3_c
31db0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d lear_bindings()]
31dc0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 to reset the bi
31dd0 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ndings..**.** ^T
31de0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 he [sqlite3_rese
31df0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 t(S)] interface
31e00 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 resets the [prep
31e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
31e20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 S.** back to the
31e30 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 beginning of it
31e40 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a s program..**.**
31e50 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
31e60 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cent call to [sq
31e70 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 lite3_step(S)] f
31e80 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 or the.** [prepa
31e90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
31ea0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
31eb0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 E_ROW] or [SQLIT
31ec0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 E_DONE],.** or i
31ed0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 f [sqlite3_step(
31ee0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 S)] has never be
31ef0 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 fore been called
31f00 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b on S,.** then [
31f10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
31f20 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 ] returns [SQLIT
31f30 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 E_OK]..**.** ^If
31f40 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
31f50 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
31f60 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 3_step(S)] for t
31f70 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
31f80 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 statement] S ind
31f90 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c icated an error,
31fa0 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 then.** [sqlite
31fb0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 3_reset(S)] retu
31fc0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 rns an appropria
31fd0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e te [error code].
31fe0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c .**.** ^The [sql
31ff0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 ite3_reset(S)] i
32000 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f nterface does no
32010 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c t change the val
32020 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 ues.** of any [s
32030 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
32040 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 |bindings] on th
32050 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
32060 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c ement] S..*/.SQL
32070 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
32080 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
32090 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 e3_reset(sqlite3
320a0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
320b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
320c0 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 Create Or Redefi
320d0 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 ne SQL Functions
320e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 .** KEYWORDS: {f
320f0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e unction creation
32100 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 routines}.** KE
32110 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 YWORDS: {applica
32120 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
32130 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 function}.** KE
32140 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 YWORDS: {applica
32150 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
32160 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d functions}.** M
32170 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
32180 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 *.** ^These func
32190 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 tions (collectiv
321a0 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 ely known as "fu
321b0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 nction creation
321c0 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 routines").** ar
321d0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 e used to add SQ
321e0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 L functions or a
321f0 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 ggregates or to
32200 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 redefine the beh
32210 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 avior.** of exis
32220 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f ting SQL functio
32230 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 ns or aggregates
32240 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 . The only diff
32250 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a erences between.
32260 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 ** these routine
32270 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 s are the text e
32280 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 ncoding expected
32290 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f for.** the seco
322a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 nd parameter (th
322b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 e name of the fu
322c0 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 nction being cre
322d0 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 ated).** and the
322e0 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 presence or abs
322f0 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 ence of a destru
32300 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f ctor callback fo
32310 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 r.** the applica
32320 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 tion data pointe
32330 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 r..**.** ^The fi
32340 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
32350 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
32360 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 onnection] to wh
32370 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 ich the SQL.** f
32380 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 unction is to be
32390 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 added. ^If an
323a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 application uses
323b0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 more than one d
323c0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
323d0 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 ction then appli
323e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
323f0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 QL functions mus
32400 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f t be added.** to
32410 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 each database c
32420 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 onnection separa
32430 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tely..**.** ^The
32440 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
32450 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 r is the name of
32460 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
32470 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 n to be created
32480 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e or.** redefined.
32490 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 ^The length of
324a0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d the name is lim
324b0 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 ited to 255 byte
324c0 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 s in a UTF-8.**
324d0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 representation,
324e0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 exclusive of the
324f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 zero-terminator
32500 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 . ^Note that th
32510 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 e name.** length
32520 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 limit is in UTF
32530 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 -8 bytes, not ch
32540 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 aracters nor UTF
32550 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 -16 bytes. .**
32560 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 ^Any attempt to
32570 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f create a functio
32580 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 n with a longer
32590 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 name.** will res
325a0 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d ult in [SQLITE_M
325b0 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 ISUSE] being ret
325c0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 urned..**.** ^Th
325d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
325e0 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 r (nArg).** is t
325f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 he number of arg
32600 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 uments that the
32610 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
32620 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b ** aggregate tak
32630 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 es. ^If this par
32640 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 ameter is -1, th
32650 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 en the SQL funct
32660 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 ion or.** aggreg
32670 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 ate may take any
32680 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d number of argum
32690 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 ents between 0 a
326a0 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 nd the limit.**
326b0 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f set by [sqlite3_
326c0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c limit]([SQLITE_L
326d0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
326e0 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 G]). If the thi
326f0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 rd.** parameter
32700 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 is less than -1
32710 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 or greater than
32720 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 127 then the beh
32730 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 avior is.** unde
32740 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
32750 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
32760 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 er, eTextRep, sp
32770 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 ecifies what.**
32780 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 [SQLITE_UTF8 | t
32790 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 ext encoding] th
327a0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 is SQL function
327b0 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 prefers for.** i
327c0 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ts parameters.
327d0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
327e0 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 should set this
327f0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
32800 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d [SQLITE_UTF16LE]
32810 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e if the function
32820 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
32830 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c invokes .** [sql
32840 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
32850 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 6le()] on an inp
32860 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 ut, or [SQLITE_U
32870 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a TF16BE] if the.*
32880 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
32890 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 invokes [sqlite
328a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
328b0 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c ()] on an input,
328c0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 or.** [SQLITE_U
328d0 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 TF16] if [sqlite
328e0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
328f0 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 ] is used, or [S
32900 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f QLITE_UTF8].** o
32910 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 therwise. ^The
32920 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f same SQL functio
32930 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 n may be registe
32940 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d red multiple tim
32950 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 es using.** diff
32960 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 erent preferred
32970 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 text encodings,
32980 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 with different i
32990 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 mplementations f
329a0 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 or.** each encod
329b0 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 ing..** ^When mu
329c0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 ltiple implement
329d0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
329e0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 me function are
329f0 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 available, SQLit
32a00 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 e.** will pick t
32a10 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f he one that invo
32a20 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 lves the least a
32a30 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f mount of data co
32a40 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nversion..**.**
32a50 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 ^The fourth para
32a60 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e meter may option
32a70 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 ally be ORed wit
32a80 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d h [SQLITE_DETERM
32a90 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 INISTIC].** to s
32aa0 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 ignal that the f
32ab0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 unction will alw
32ac0 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 ays return the s
32ad0 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e ame result given
32ae0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 .** the same inp
32af0 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e uts within a sin
32b00 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e gle SQL statemen
32b10 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e t. Most SQL fun
32b20 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 ctions are.** de
32b30 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 terministic. Th
32b40 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 e built-in [rand
32b50 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 om()] SQL functi
32b60 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 on is an example
32b70 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f of a.** functio
32b80 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 n that is not de
32b90 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 terministic. Th
32ba0 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 e SQLite query p
32bb0 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 lanner is able t
32bc0 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 o.** perform add
32bd0 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 itional optimiza
32be0 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 tions on determi
32bf0 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 nistic functions
32c00 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 , so use.** of t
32c10 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 he [SQLITE_DETER
32c20 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 MINISTIC] flag i
32c30 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 s recommended wh
32c40 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a ere possible..**
32c50 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 .** ^(The fifth
32c60 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 parameter is an
32c70 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 arbitrary pointe
32c80 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e r. The implemen
32c90 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a tation of the.**
32ca0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 function can ga
32cb0 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 in access to thi
32cc0 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 s pointer using
32cd0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 [sqlite3_user_da
32ce0 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e ta()].)^.**.** ^
32cf0 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e The sixth, seven
32d00 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 th and eighth pa
32d10 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c rameters, xFunc,
32d20 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 xStep and xFina
32d30 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 l, are.** pointe
32d40 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 rs to C-language
32d50 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
32d60 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 implement the SQ
32d70 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a L function or.**
32d80 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 aggregate. ^A s
32d90 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 calar SQL functi
32da0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 on requires an i
32db0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
32dc0 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 the xFunc.** ca
32dd0 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c llback only; NUL
32de0 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 L pointers must
32df0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
32e00 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 xStep and xFina
32e10 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e l.** parameters.
32e20 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 ^An aggregate S
32e30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 QL function requ
32e40 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e ires an implemen
32e50 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a tation of xStep.
32e60 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e ** and xFinal an
32e70 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d d NULL pointer m
32e80 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f ust be passed fo
32e90 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c r xFunc. ^To del
32ea0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a ete an existing.
32eb0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ** SQL function
32ec0 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 or aggregate, pa
32ed0 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 ss NULL pointers
32ee0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 for all three f
32ef0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 unction.** callb
32f00 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 acks..**.** ^(If
32f10 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d the ninth param
32f20 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
32f30 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
32f40 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c v2() is not NULL
32f50 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 ,.** then it is
32f60 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 destructor for t
32f70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
32f80 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a ata pointer. .**
32f90 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 The destructor
32fa0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 is invoked when
32fb0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 the function is
32fc0 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 deleted, either
32fd0 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 by being.** over
32fe0 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 loaded or when t
32ff0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
33000 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e ection closes.)^
33010 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 .** ^The destruc
33020 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f tor is also invo
33030 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 ked if the call
33040 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 to.** sqlite3_cr
33050 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 eate_function_v2
33060 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 () fails..** ^Wh
33070 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f en the destructo
33080 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 r callback of th
33090 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 e tenth paramete
330a0 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 r is invoked, it
330b0 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 .** is passed a
330c0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
330d0 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 which is a copy
330e0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
330f0 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e on data .** poin
33100 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 ter which was th
33110 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 e fifth paramete
33120 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 r to sqlite3_cre
33130 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
33140 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 )..**.** ^It is
33150 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 permitted to reg
33160 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 ister multiple i
33170 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
33180 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 f the same.** fu
33190 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 nctions with the
331a0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 same name but w
331b0 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 ith either diffe
331c0 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a ring numbers of.
331d0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 ** arguments or
331e0 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 differing prefer
331f0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
33200 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c gs. ^SQLite wil
33210 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 l use.** the imp
33220 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 lementation that
33230 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 most closely ma
33240 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e tches the way in
33250 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 which the.** SQ
33260 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 L function is us
33270 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e ed. ^A function
33280 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
33290 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 with a non-negat
332a0 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 ive.** nArg para
332b0 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 meter is a bette
332c0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 r match than a f
332d0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
332e0 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 tation with.** a
332f0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 negative nArg.
33300 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 ^A function whe
33310 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 re the preferred
33320 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a text encoding.*
33330 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 * matches the da
33340 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 tabase encoding
33350 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d is a better.** m
33360 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 atch than a func
33370 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 tion where the e
33380 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 ncoding is diffe
33390 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 rent. .** ^A fu
333a0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
333b0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 encoding differ
333c0 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 ence is between
333d0 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 UTF16le and UTF1
333e0 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 6be.** is a clos
333f0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 er match than a
33400 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
33410 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 he encoding diff
33420 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 erence is.** bet
33430 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 ween UTF8 and UT
33440 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c F16..**.** ^Buil
33450 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d t-in functions m
33460 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 ay be overloaded
33470 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 by new applicat
33480 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
33490 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e tions..**.** ^An
334a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
334b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 ined function is
334c0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 permitted to ca
334d0 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 ll other.** SQLi
334e0 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 te interfaces.
334f0 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 However, such ca
33500 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 lls must not.**
33510 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 close the databa
33520 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f se connection no
33530 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 r finalize or re
33540 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 set the prepared
33550 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e .** statement in
33560 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 which the funct
33570 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
33580 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
33590 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
335a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
335b0 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 function(. sqli
335c0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 te3 *db,. const
335d0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e char *zFunction
335e0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
335f0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
33600 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a ,. void *pApp,.
33610 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 void (*xFunc)(
33620 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
33630 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
33640 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
33650 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 xStep)(sqlite3_c
33660 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
33670 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
33680 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 void (*xFinal)(s
33690 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
336a0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
336b0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
336c0 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 L sqlite3_create
336d0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 _function16(. s
336e0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f qlite3 *db,. co
336f0 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 nst void *zFunct
33700 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e ionName,. int n
33710 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 Arg,. int eText
33720 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 Rep,. void *pAp
33730 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e p,. void (*xFun
33740 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 c)(sqlite3_conte
33750 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
33760 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
33770 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 (*xStep)(sqlite
33780 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
33790 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
337a0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c . void (*xFinal
337b0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
337c0 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 t*).);.SQLITE_AP
337d0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
337e0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 CALL sqlite3_cre
337f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
33800 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a . sqlite3 *db,.
33810 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 const char *zF
33820 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 unctionName,. i
33830 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 nt nArg,. int e
33840 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 TextRep,. void
33850 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a *pApp,. void (*
33860 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
33870 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
33880 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
33890 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 void (*xStep)(sq
338a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
338b0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
338c0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 **),. void (*xF
338d0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f inal)(sqlite3_co
338e0 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 ntext*),. void(
338f0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a *xDestroy)(void*
33900 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ).);../*.** CAPI
33910 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 3REF: Text Encod
33920 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ings.**.** These
33930 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 constant define
33940 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 integer codes t
33950 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 hat represent th
33960 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 e various.** tex
33970 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 t encodings supp
33980 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e orted by SQLite.
33990 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
339a0 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 TE_UTF8
339b0 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 1 /* IMP: R
339c0 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a -37514-35566 */.
339d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
339e0 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 TF16LE 2
339f0 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 /* IMP: R-033
33a00 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 71-37637 */.#def
33a10 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
33a20 42 45 20 20 20 20 20 20 20 20 33 20 20 20 20 2f BE 3 /
33a30 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 * IMP: R-51971-3
33a40 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 4154 */.#define
33a50 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 SQLITE_UTF16
33a60 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 4 /* Us
33a70 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
33a80 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 der */.#define S
33a90 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 QLITE_ANY
33aa0 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 5 /* Dep
33ab0 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 recated */.#defi
33ac0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f ne SQLITE_UTF16_
33ad0 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a ALIGNED 8 /*
33ae0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
33af0 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a collation only *
33b00 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
33b10 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 F: Function Flag
33b20 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f s.**.** These co
33b30 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f nstants may be O
33b40 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 Red together wit
33b50 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 h the .** [SQLIT
33b60 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 E_UTF8 | preferr
33b70 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ed text encoding
33b80 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 ] as the fourth
33b90 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b argument.** to [
33ba0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
33bb0 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c unction()], [sql
33bc0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
33bd0 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a tion16()], or.**
33be0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
33bf0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e _function_v2()].
33c00 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
33c10 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 TE_DETERMINISTIC
33c20 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 0x800../*.**
33c30 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 CAPI3REF: Depre
33c40 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a cated Functions.
33c50 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a ** DEPRECATED.**
33c60 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
33c70 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 ons are [depreca
33c80 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 ted]. In order
33c90 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 to maintain.** b
33ca0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
33cb0 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 bility with olde
33cc0 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 r code, these fu
33cd0 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 nctions continue
33ce0 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f .** to be suppo
33cf0 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 rted. However,
33d00 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 new applications
33d10 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a should avoid.**
33d20 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 the use of thes
33d30 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f e functions. To
33d40 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72 encourage progr
33d50 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a ammers to avoid.
33d60 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f ** these functio
33d70 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 ns, we will not
33d80 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65 explain what the
33d90 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 y do..*/.#ifndef
33da0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 SQLITE_OMIT_DEP
33db0 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 RECATED.SQLITE_A
33dc0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 PI SQLITE_DEPREC
33dd0 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f ATED int SQLITE_
33de0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
33df0 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 aggregate_count(
33e00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
33e10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 );.SQLITE_API SQ
33e20 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
33e30 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
33e40 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 LL sqlite3_expir
33e50 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ed(sqlite3_stmt*
33e60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 );.SQLITE_API SQ
33e70 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
33e80 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
33e90 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 LL sqlite3_trans
33ea0 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c fer_bindings(sql
33eb0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 ite3_stmt*, sqli
33ec0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
33ed0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
33ee0 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c PRECATED int SQL
33ef0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
33f00 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 te3_global_recov
33f10 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 er(void);.SQLITE
33f20 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 _API SQLITE_DEPR
33f30 45 43 41 54 45 44 20 76 6f 69 64 20 53 51 4c 49 ECATED void SQLI
33f40 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
33f50 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 e3_thread_cleanu
33f60 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f p(void);.SQLITE_
33f70 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
33f80 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 CATED int SQLITE
33f90 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
33fa0 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f _memory_alarm(vo
33fb0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
33fc0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a te3_int64,int),.
33fd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
33fe0 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 void*,sqli
33ff0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 te3_int64);.#end
34000 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 if../*.** CAPI3R
34010 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 EF: Obtaining SQ
34020 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 L Values.** METH
34030 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 OD: sqlite3_valu
34040 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 e.**.** The C-la
34050 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 nguage implement
34060 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e ation of SQL fun
34070 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 ctions and aggre
34080 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 gates uses.** th
34090 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 is set of interf
340a0 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ace routines to
340b0 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d access the param
340c0 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a eter values on.*
340d0 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f * the function o
340e0 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a r aggregate. .*
340f0 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 *.** The xFunc (
34100 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 for scalar funct
34110 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 ions) or xStep (
34120 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 for aggregates)
34130 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f parameters.** to
34140 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
34150 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 _function()] and
34160 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
34170 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a _function16()].*
34180 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 * define callbac
34190 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ks that implemen
341a0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
341b0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 ons and aggregat
341c0 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 es..** The 3rd p
341d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 arameter to thes
341e0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 e callbacks is a
341f0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
34200 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 ers to.** [prote
34210 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
34220 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 ue] objects. Th
34230 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 ere is one [sqli
34240 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
34250 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 t for.** each pa
34260 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 rameter to the S
34270 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 QL function. Th
34280 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
34290 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 used to.** extr
342a0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 act values from
342b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
342c0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a ue] objects..**.
342d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
342e0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 s work only with
342f0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
34300 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
34310 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d ts..** Any attem
34320 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 pt to use these
34330 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b routines on an [
34340 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
34350 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 te3_value].** ob
34360 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 ject results in
34370 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 undefined behavi
34380 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 or..**.** ^These
34390 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a routines work j
343a0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 ust like the cor
343b0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 responding [colu
343c0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 mn access functi
343d0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 ons].** except t
343e0 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e hat these routin
343f0 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 es take a single
34400 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
34410 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
34420 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 t.** pointer ins
34430 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 tead of a [sqlit
34440 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 e3_stmt*] pointe
34450 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 r and an integer
34460 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a column number..
34470 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
34480 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
34490 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 ) interface extr
344a0 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 acts a UTF-16 st
344b0 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e ring.** in the n
344c0 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 ative byte-order
344d0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 of the host mac
344e0 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 hine. ^The.** s
344f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
34500 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 t16be() and sqli
34510 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
34520 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a le() interfaces.
34530 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 ** extract UTF-1
34540 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 6 strings as big
34550 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 -endian and litt
34560 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 le-endian respec
34570 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 tively..**.** ^(
34580 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
34590 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 e_numeric_type()
345a0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
345b0 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 pts to apply.**
345c0 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 numeric affinity
345d0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 to the value.
345e0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 This means that
345f0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a an attempt is.**
34600 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 made to convert
34610 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e the value to an
34620 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 integer or floa
34630 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a ting point. If.
34640 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 ** such a conver
34650 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 sion is possible
34660 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 without loss of
34670 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e information (in
34680 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c other.** words,
34690 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 if the value is
346a0 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c a string that l
346b0 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 ooks like a numb
346c0 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 er).** then the
346d0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 conversion is pe
346e0 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 rformed. Otherw
346f0 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f ise no conversio
34700 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 n occurs..** The
34710 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
34720 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 | datatype] aft
34730 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 er conversion is
34740 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a returned.)^.**.
34750 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 ** Please pay pa
34760 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 rticular attenti
34770 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 on to the fact t
34780 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 hat the pointer
34790 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d returned.** from
347a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
347b0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 blob()], [sqlite
347c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 3_value_text()],
347d0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
347e0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 value_text16()]
347f0 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 can be invalidat
34800 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 ed by a subseque
34810 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 nt call to.** [s
34820 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
34830 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f es()], [sqlite3_
34840 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d value_bytes16()]
34850 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
34860 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 _text()],.** or
34870 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
34880 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 ext16()]..**.**
34890 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d These routines m
348a0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
348b0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
348c0 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c ad as.** the SQL
348d0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 function that s
348e0 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c upplied the [sql
348f0 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 ite3_value*] par
34900 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 ameters..*/.SQLI
34910 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
34920 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
34930 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f L sqlite3_value_
34940 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c blob(sqlite3_val
34950 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
34960 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
34970 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ALL sqlite3_valu
34980 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f e_bytes(sqlite3_
34990 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
349a0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
349b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
349c0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c alue_bytes16(sql
349d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
349e0 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 LITE_API double
349f0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
34a00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 qlite3_value_dou
34a10 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ble(sqlite3_valu
34a20 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
34a30 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
34a40 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 LL sqlite3_value
34a50 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c _int(sqlite3_val
34a60 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
34a70 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 sqlite3_int64 S
34a80 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
34a90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 lite3_value_int6
34aa0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 4(sqlite3_value*
34ab0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
34ac0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 nst unsigned cha
34ad0 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c r *SQLITE_STDCAL
34ae0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f L sqlite3_value_
34af0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c text(sqlite3_val
34b00 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
34b10 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c const void *SQL
34b20 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
34b30 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
34b40 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
34b50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
34b60 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f st void *SQLITE_
34b70 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
34b80 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 value_text16le(s
34b90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
34ba0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
34bb0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
34bc0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 DCALL sqlite3_va
34bd0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c lue_text16be(sql
34be0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
34bf0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
34c00 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
34c10 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 te3_value_type(s
34c20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
34c30 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
34c40 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
34c50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 lite3_value_nume
34c60 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 ric_type(sqlite3
34c70 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _value*);../*.**
34c80 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20 CAPI3REF: Copy
34c90 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c And Free SQL Val
34ca0 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ues.** METHOD: s
34cb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a qlite3_value.**.
34cc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
34cd0 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 value_dup(V) int
34ce0 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 erface makes a c
34cf0 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 opy of the [sqli
34d00 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 te3_value].** ob
34d10 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74 75 72 ject D and retur
34d20 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
34d30 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 that copy. ^The
34d40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
34d50 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 returned.** is
34d60 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c a [protected sql
34d70 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
34d80 63 74 20 65 76 65 6e 20 69 66 20 74 68 65 20 69 ct even if the i
34d90 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 nput is not..**
34da0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
34db0 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 ue_dup(V) interf
34dc0 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c ace returns NULL
34dd0 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 if V is NULL or
34de0 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 if a.** memory
34df0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 allocation fails
34e00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
34e10 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 ite3_value_free(
34e20 56 29 20 69 6e 74 65 72 66 61 63 65 20 66 72 65 V) interface fre
34e30 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 es an [sqlite3_v
34e40 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 alue] object.**
34e50 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
34e60 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
34e70 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 3_value_dup()].
34e80 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c ^If V is a NULL
34e90 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e pointer.** then
34ea0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 sqlite3_value_f
34eb0 72 65 65 28 56 29 20 69 73 20 61 20 68 61 72 6d ree(V) is a harm
34ec0 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 less no-op..*/.S
34ed0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
34ee0 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 73 71 _EXPERIMENTAL sq
34ef0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 53 51 4c lite3_value *SQL
34f00 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
34f10 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f te3_value_dup(co
34f20 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 nst sqlite3_valu
34f30 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
34f40 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
34f50 54 41 4c 20 76 6f 69 64 20 53 51 4c 49 54 45 5f TAL void SQLITE_
34f60 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
34f70 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74 value_free(sqlit
34f80 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a e3_value*);../*.
34f90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
34fa0 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 ain Aggregate Fu
34fb0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a nction Context.*
34fc0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
34fd0 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 3_context.**.**
34fe0 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 Implementations
34ff0 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c of aggregate SQL
35000 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 functions use t
35010 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 his.** routine t
35020 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 o allocate memor
35030 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 y for storing th
35040 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a eir state..**.**
35050 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 ^The first time
35060 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 the sqlite3_agg
35070 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
35080 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 ,N) routine is c
35090 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 alled .** for a
350a0 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 particular aggre
350b0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 gate function, S
350c0 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 QLite.** allocat
350d0 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 es N of memory,
350e0 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 zeroes out that
350f0 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 memory, and retu
35100 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a rns a pointer.**
35110 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f to the new memo
35120 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 ry. ^On second a
35130 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 nd subsequent ca
35140 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 lls to.** sqlite
35150 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
35160 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 ext() for the sa
35170 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e me aggregate fun
35180 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a ction instance,.
35190 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 ** the same buff
351a0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 er is returned.
351b0 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 Sqlite3_aggrega
351c0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 te_context() is
351d0 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c normally.** call
351e0 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 ed once for each
351f0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 invocation of t
35200 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 he xStep callbac
35210 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a k and then one.*
35220 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e * last time when
35230 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c the xFinal call
35240 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e back is invoked.
35250 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 ^(When no rows
35260 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 match.** an agg
35270 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 regate query, th
35280 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 e xStep() callba
35290 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 ck of the aggreg
352a0 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ate function.**
352b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
352c0 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 s never called a
352d0 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 nd xFinal() is c
352e0 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e alled exactly on
352f0 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 ce..** In those
35300 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 cases, sqlite3_a
35310 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
35320 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c () might be call
35330 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 ed for the.** fi
35340 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 rst time from wi
35350 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e thin xFinal().)^
35360 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
35370 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
35380 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 ntext(C,N) routi
35390 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c ne returns a NUL
353a0 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 L pointer .** wh
353b0 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 en first called
353c0 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 if N is less tha
353d0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 n or equal to ze
353e0 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 ro or if a memor
353f0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 y.** allocate er
35400 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a ror occurs..**.*
35410 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f * ^(The amount o
35420 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 f space allocate
35430 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 d by sqlite3_agg
35440 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
35450 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d ,N) is.** determ
35460 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 ined by the N pa
35470 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 rameter on first
35480 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
35490 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a . Changing the.
354a0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e ** value of N in
354b0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
354c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 to sqlite3_aggr
354d0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
354e0 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 within.** the sa
354f0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e me aggregate fun
35500 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 ction instance w
35510 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 ill not resize t
35520 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c he memory.** all
35530 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 ocation.)^ With
35540 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 in the xFinal ca
35550 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 llback, it is cu
35560 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a stomary to set.*
35570 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 * N=0 in calls t
35580 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 o sqlite3_aggreg
35590 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
355a0 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 so that no .**
355b0 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 pointless memory
355c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 allocations occ
355d0 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 ur..**.** ^SQLit
355e0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
355f0 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 frees the memory
35600 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a allocated by .*
35610 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 * sqlite3_aggreg
35620 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 ate_context() wh
35630 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 en the aggregate
35640 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 query concludes
35650 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
35660 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 t parameter must
35670 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 be a copy of th
35680 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
35690 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 ntext | SQL func
356a0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 tion context] th
356b0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 at is the first
356c0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 parameter.** to
356d0 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 the xStep or xFi
356e0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 nal callback rou
356f0 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d tine that implem
35700 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 ents the aggrega
35710 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a te.** function..
35720 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
35730 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ne must be calle
35740 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
35750 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a thread in which.
35760 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 ** the aggregate
35770 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 SQL function is
35780 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c running..*/.SQL
35790 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 ITE_API void *SQ
357a0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
357b0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
357c0 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 ontext(sqlite3_c
357d0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 ontext*, int nBy
357e0 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tes);../*.** CAP
357f0 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 I3REF: User Data
35800 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a For Functions.*
35810 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
35820 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 3_context.**.**
35830 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 ^The sqlite3_use
35840 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 r_data() interfa
35850 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 ce returns a cop
35860 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e y of.** the poin
35870 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 ter that was the
35880 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d pUserData param
35890 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 eter (the 5th pa
358a0 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 rameter).** of t
358b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
358c0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a te_function()].*
358d0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
358e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
358f0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 ()] routines tha
35900 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 t originally.**
35910 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 registered the a
35920 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
35930 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a ed function..**.
35940 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
35950 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
35960 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
35970 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
35980 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
35990 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
359a0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a is running..*/.
359b0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
359c0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
359d0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
359e0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
359f0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
35a00 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
35a10 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 onnection For Fu
35a20 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f nctions.** METHO
35a30 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 D: sqlite3_conte
35a40 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 xt.**.** ^The sq
35a50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
35a60 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 _handle() interf
35a70 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f ace returns a co
35a80 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 py of.** the poi
35a90 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 nter to the [dat
35aa0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
35ab0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d ] (the 1st param
35ac0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 eter).** of the
35ad0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
35ae0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 function()].** a
35af0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
35b00 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
35b10 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f routines that o
35b20 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 riginally.** reg
35b30 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c istered the appl
35b40 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 ication defined
35b50 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c function..*/.SQL
35b60 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 ITE_API sqlite3
35b70 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
35b80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f sqlite3_context_
35b90 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 db_handle(sqlite
35ba0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 3_context*);../*
35bb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 .** CAPI3REF: Fu
35bc0 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 nction Auxiliary
35bd0 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a Data.** METHOD:
35be0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
35bf0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e .**.** These fun
35c00 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 ctions may be us
35c10 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 ed by (non-aggre
35c20 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 gate) SQL functi
35c30 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 ons to.** associ
35c40 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 ate metadata wit
35c50 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 h argument value
35c60 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 s. If the same v
35c70 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 alue is passed t
35c80 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e o.** multiple in
35c90 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 vocations of the
35ca0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 same SQL functi
35cb0 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 on during query
35cc0 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 execution, under
35cd0 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 .** some circums
35ce0 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 tances the assoc
35cf0 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d iated metadata m
35d00 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e ay be preserved.
35d10 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 An example.**
35d20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 of where this mi
35d30 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 ght be useful is
35d40 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 in a regular-ex
35d50 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e pression matchin
35d60 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 g.** function. T
35d70 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 he compiled vers
35d80 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c ion of the regul
35d90 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 ar expression ca
35da0 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a n be stored as.*
35db0 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 * metadata assoc
35dc0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70 iated with the p
35dd0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 attern string.
35de0 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 .** Then as long
35df0 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 as the pattern
35e00 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 string remains t
35e10 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 he same,.** the
35e20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 compiled regular
35e30 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 expression can
35e40 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c be reused on mul
35e50 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 tiple.** invocat
35e60 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
35e70 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
35e80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 ^The sqlite3_ge
35e90 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 t_auxdata() inte
35ea0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
35eb0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d pointer to the m
35ec0 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 etadata.** assoc
35ed0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c iated by the sql
35ee0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
35ef0 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 () function with
35f00 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e the Nth argumen
35f10 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 t.** value to th
35f20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
35f30 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 fined function.
35f40 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 ^If there is no
35f50 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f metadata.** asso
35f60 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
35f70 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e function argumen
35f80 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f t, this sqlite3_
35f90 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e get_auxdata() in
35fa0 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 terface.** retur
35fb0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
35fc0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 r..**.** ^The sq
35fd0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
35fe0 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 a(C,N,P,X) inter
35ff0 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20 face saves P as
36000 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 metadata for the
36010 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e N-th.** argumen
36020 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 t of the applica
36030 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
36040 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 ction. ^Subsequ
36050 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 ent.** calls to
36060 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
36070 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 ata(C,N) return
36080 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 P from the most
36090 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 recent.** sqlite
360a0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 3_set_auxdata(C,
360b0 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 N,P,X) call if t
360c0 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 he metadata is s
360d0 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a till valid or.**
360e0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 NULL if the met
360f0 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 adata has been d
36100 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 iscarded..** ^Af
36110 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f ter each call to
36120 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
36130 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 data(C,N,P,X) wh
36140 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c ere X is not NUL
36150 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c L,.** SQLite wil
36160 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 l invoke the des
36170 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e tructor function
36180 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 X with paramete
36190 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f r P exactly.** o
361a0 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 nce, when the me
361b0 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72 tadata is discar
361c0 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ded..** SQLite i
361d0 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 s free to discar
361e0 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 d the metadata a
361f0 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c t any time, incl
36200 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c uding: <ul>.** <
36210 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 li> when the cor
36220 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 responding funct
36230 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 ion parameter ch
36240 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 anges, or.** <li
36250 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f > when [sqlite3_
36260 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c reset()] or [sql
36270 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
36280 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 is called for t
36290 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 he.** SQL s
362a0 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 tatement, or.**
362b0 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 <li> when sqlite
362c0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_set_auxdata()
362d0 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e is invoked again
362e0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 on the same par
362f0 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c ameter, or.** <l
36300 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 i> during the or
36310 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 iginal sqlite3_s
36320 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c et_auxdata() cal
36330 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 l when a memory
36340 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 .** allocat
36350 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ion error occurs
36360 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 . </ul>)^.**.**
36370 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 Note the last bu
36380 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c llet in particul
36390 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 ar. The destruc
363a0 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c tor X in .** sql
363b0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
363c0 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 (C,N,P,X) might
363d0 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 be called immedi
363e0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 ately, before th
363f0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 e.** sqlite3_set
36400 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 _auxdata() inter
36410 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e face even return
36420 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 s. Hence sqlite
36430 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 3_set_auxdata().
36440 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c ** should be cal
36450 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 led near the end
36460 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e of the function
36470 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
36480 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 and the.** funct
36490 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
364a0 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 on should not ma
364b0 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 ke any use of P
364c0 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 after.** sqlite3
364d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 _set_auxdata() h
364e0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a as been called..
364f0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 **.** ^(In pract
36500 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 ice, metadata is
36510 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 preserved betwe
36520 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c en function call
36530 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f s for.** functio
36540 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 n parameters tha
36550 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 t are compile-ti
36560 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e me constants, in
36570 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a cluding literal.
36580 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 ** values and [p
36590 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 arameters] and e
365a0 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f xpressions compo
365b0 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d sed from the sam
365c0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 e.)^.**.** These
365d0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 routines must b
365e0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
365f0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
36600 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 which.** the SQ
36610 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 L function is ru
36620 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 nning..*/.SQLITE
36630 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 _API void *SQLIT
36640 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
36650 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 3_get_auxdata(sq
36660 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
36670 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 int N);.SQLITE_A
36680 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 PI void SQLITE_S
36690 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 TDCALL sqlite3_s
366a0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 et_auxdata(sqlit
366b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
366c0 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 N, void*, void
366d0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f (*)(void*));.../
366e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
366f0 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e onstants Definin
36700 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 g Special Destru
36710 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a ctor Behavior.**
36720 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 .** These are sp
36730 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 ecial values for
36740 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
36750 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 that is passed i
36760 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 n as the.** fina
36770 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f l argument to ro
36780 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c utines like [sql
36790 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
367a0 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 ()]. ^If the de
367b0 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 structor.** argu
367c0 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 ment is SQLITE_S
367d0 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 TATIC, it means
367e0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 that the content
367f0 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 pointer is cons
36800 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c tant.** and will
36810 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 never change.
36820 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 It does not need
36830 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 to be destroyed
36840 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 . ^The.** SQLIT
36850 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 E_TRANSIENT valu
36860 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 e means that the
36870 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 content will li
36880 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a kely change in.*
36890 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 * the near futur
368a0 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 e and that SQLit
368b0 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 e should make it
368c0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f s own private co
368d0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e py of.** the con
368e0 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 tent before retu
368f0 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rning..**.** The
36900 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 typedef is nece
36910 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 ssary to work ar
36920 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e ound problems in
36930 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 certain.** C++
36940 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 compilers..*/.ty
36950 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c pedef void (*sql
36960 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f ite3_destructor_
36970 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 type)(void*);.#d
36980 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 efine SQLITE_STA
36990 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 TIC ((sqlit
369a0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 e3_destructor_ty
369b0 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 pe)0).#define SQ
369c0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 LITE_TRANSIENT
369d0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 ((sqlite3_destr
369e0 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a uctor_type)-1)..
369f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
36a00 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 Setting The Resu
36a10 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e lt Of An SQL Fun
36a20 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a ction.** METHOD:
36a30 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
36a40 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
36a50 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 tines are used b
36a60 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 y the xFunc or x
36a70 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 Final callbacks
36a80 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e that.** implemen
36a90 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 t SQL functions
36aa0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 and aggregates.
36ab0 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 See.** [sqlite3
36ac0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
36ad0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
36ae0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
36af0 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 16()].** for add
36b00 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
36b10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ion..**.** These
36b20 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 functions work
36b30 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 very much like t
36b40 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 he [parameter bi
36b50 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 nding] family of
36b60 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 .** functions us
36b70 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 ed to bind value
36b80 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 s to host parame
36b90 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 ters in prepared
36ba0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 statements..**
36bb0 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 Refer to the [SQ
36bc0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 L parameter] doc
36bd0 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 umentation for a
36be0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
36bf0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ation..**.** ^Th
36c00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
36c10 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 _blob() interfac
36c20 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
36c30 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 t from.** an app
36c40 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
36c50 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
36c60 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 the BLOB whose c
36c70 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 ontent is pointe
36c80 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 d.** to by the s
36c90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
36ca0 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 and which is N b
36cb0 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 ytes long where
36cc0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 N is the.** thir
36cd0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a d parameter..**.
36ce0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
36cf0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 result_zeroblob(
36d00 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 ) interfaces set
36d10 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a the result of.*
36d20 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f * the applicatio
36d30 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
36d40 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 on to be a BLOB
36d50 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a containing all z
36d60 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 ero.** bytes and
36d70 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 N bytes in size
36d80 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
36d90 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e value of the 2n
36da0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a d parameter..**.
36db0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
36dc0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 result_double()
36dd0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
36de0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a he result from.*
36df0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e * an application
36e00 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
36e10 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 n to be a floati
36e20 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 ng point value s
36e30 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 pecified.** by i
36e40 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e ts 2nd argument.
36e50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
36e60 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
36e70 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
36e80 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
36e90 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 functions.** cau
36ea0 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 se the implement
36eb0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ed SQL function
36ec0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 to throw an exce
36ed0 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 ption..** ^SQLit
36ee0 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e e uses the strin
36ef0 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 g pointed to by
36f00 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d the.** 2nd param
36f10 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f eter of sqlite3_
36f20 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f result_error() o
36f30 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
36f40 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 _error16().** as
36f50 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 the text of an
36f60 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 error message.
36f70 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 ^SQLite interpre
36f80 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 ts the error.**
36f90 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 message string f
36fa0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 rom sqlite3_resu
36fb0 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 lt_error() as UT
36fc0 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 F-8. ^SQLite.**
36fd0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 interprets the s
36fe0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 tring from sqlit
36ff0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
37000 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 6() as UTF-16 in
37010 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 native.** byte
37020 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 order. ^If the
37030 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
37040 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
37050 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 t_error().** or
37060 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
37070 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 rror16() is nega
37080 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 tive then SQLite
37090 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 takes as the er
370a0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 ror.** message a
370b0 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 ll text up throu
370c0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 gh the first zer
370d0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 o character..**
370e0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 ^If the third pa
370f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
37100 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
37110 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
37120 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
37130 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
37140 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b then SQLite tak
37150 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 es that many.**
37160 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 bytes (not chara
37170 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 cters) from the
37180 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 2nd parameter as
37190 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
371a0 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 ge..** ^The sqli
371b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
371c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
371d0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a esult_error16().
371e0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 ** routines make
371f0 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 a private copy
37200 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 of the error mes
37210 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 sage text before
37220 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e .** they return.
37230 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c Hence, the cal
37240 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ling function ca
37250 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a n deallocate or.
37260 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 ** modify the te
37270 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 xt after they re
37280 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 turn without har
37290 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 m..** ^The sqlit
372a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
372b0 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 code() function
372c0 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f changes the erro
372d0 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e r code.** return
372e0 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 ed by SQLite as
372f0 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 a result of an e
37300 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 rror in a functi
37310 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 on. ^By default
37320 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 ,.** the error c
37330 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 ode is SQLITE_ER
37340 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 ROR. ^A subsequ
37350 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ent call to sqli
37360 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
37370 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
37380 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
37390 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 ) resets the err
373a0 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 or code to SQLIT
373b0 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e E_ERROR..**.** ^
373c0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
373d0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 lt_error_toobig(
373e0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 ) interface caus
373f0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 es SQLite to thr
37400 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 ow an.** error i
37410 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 ndicating that a
37420 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 string or BLOB
37430 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 is too long to r
37440 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 epresent..**.**
37450 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
37460 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 ult_error_nomem(
37470 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 ) interface caus
37480 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 es SQLite to thr
37490 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 ow an.** error i
374a0 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 ndicating that a
374b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
374c0 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a on failed..**.**
374d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
374e0 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 sult_int() inter
374f0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
37500 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 turn value.** of
37510 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
37520 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
37530 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 n to be the 32-b
37540 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
37550 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e r.** value given
37560 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 in the 2nd argu
37570 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 ment..** ^The sq
37580 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
37590 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 64() interface s
375a0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 ets the return v
375b0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 alue.** of the a
375c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
375d0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
375e0 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 e the 64-bit sig
375f0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 ned integer.** v
37600 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 alue given in th
37610 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a e 2nd argument..
37620 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
37630 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 e3_result_null()
37640 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
37650 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
37660 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 .** of the appli
37670 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
37680 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 unction to be NU
37690 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 LL..**.** ^The s
376a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
376b0 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 xt(), sqlite3_re
376c0 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a sult_text16(),.*
376d0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 * sqlite3_result
376e0 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 _text16le(), and
376f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37700 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 text16be() inter
37710 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 faces.** set the
37720 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
37730 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
37740 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
37750 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 n to be.** a tex
37760 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 t string which i
37770 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 s represented as
37780 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e UTF-8, UTF-16 n
37790 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
377a0 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 ,.** UTF-16 litt
377b0 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 le endian, or UT
377c0 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c F-16 big endian,
377d0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
377e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
377f0 65 73 75 6c 74 5f 74 65 78 74 36 34 28 29 20 69 esult_text64() i
37800 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
37810 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
37820 66 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 f an.** applicat
37830 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
37840 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 74 65 78 tion to be a tex
37850 74 20 73 74 72 69 6e 67 20 69 6e 20 61 6e 20 65 t string in an e
37860 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69 ncoding.** speci
37870 66 69 65 64 20 62 79 20 74 68 65 20 66 69 66 74 fied by the fift
37880 68 20 28 61 6e 64 20 6c 61 73 74 29 20 70 61 72 h (and last) par
37890 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 6d 75 ameter, which mu
378a0 73 74 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 st be one.** of
378b0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b [SQLITE_UTF8], [
378c0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b SQLITE_UTF16], [
378d0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c SQLITE_UTF16BE],
378e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 or [SQLITE_UTF1
378f0 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 6LE]..** ^SQLite
37900 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 takes the text
37910 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 result from the
37920 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d application from
37930 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 .** the 2nd para
37940 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c meter of the sql
37950 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
37960 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a * interfaces..**
37970 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 ^If the 3rd par
37980 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
37990 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
379a0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
379b0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
379c0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 en SQLite takes
379d0 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d result text from
379e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
379f0 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 er.** through th
37a00 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 e first zero cha
37a10 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 racter..** ^If t
37a20 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
37a30 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
37a40 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
37a50 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f erfaces.** is no
37a60 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e n-negative, then
37a70 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 as many bytes (
37a80 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 not characters)
37a90 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 of the text.** p
37aa0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 ointed to by the
37ab0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
37ac0 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 re taken as the
37ad0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
37ae0 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ned.** function
37af0 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 result. If the
37b00 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 3rd parameter is
37b10 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 non-negative, t
37b20 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 hen it.** must b
37b30 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 e the byte offse
37b40 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e t into the strin
37b50 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 g where the NUL
37b60 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 terminator would
37b70 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 .** appear if th
37b80 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e e string where N
37b90 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 UL terminated.
37ba0 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 If any NUL chara
37bb0 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 cters occur.** i
37bc0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 n the string at
37bd0 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 a byte offset th
37be0 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 at is less than
37bf0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
37c00 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 3rd.** paramete
37c10 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 r, then the resu
37c20 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c lting string wil
37c30 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 l contain embedd
37c40 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a ed NULs and the.
37c50 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 ** result of exp
37c60 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 ressions operati
37c70 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 ng on strings wi
37c80 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 th embedded NULs
37c90 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
37ca0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 * ^If the 4th pa
37cb0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
37cc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
37cd0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
37ce0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 * or sqlite3_res
37cf0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f ult_blob is a no
37d00 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 n-NULL pointer,
37d10 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c then SQLite call
37d20 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 s that.** functi
37d30 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 on as the destru
37d40 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 ctor on the text
37d50 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 or BLOB result
37d60 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 when it has.** f
37d70 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 inished using th
37d80 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 at result..** ^I
37d90 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 f the 4th parame
37da0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
37db0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
37dc0 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f interfaces or to
37dd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 .** sqlite3_resu
37de0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 lt_blob is the s
37df0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 pecial constant
37e00 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 SQLITE_STATIC, t
37e10 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 hen SQLite.** as
37e20 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 sumes that the t
37e30 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 ext or BLOB resu
37e40 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e lt is in constan
37e50 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 t space and does
37e60 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 not.** copy the
37e70 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
37e80 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 parameter nor ca
37e90 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 ll a destructor
37ea0 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a on the content.*
37eb0 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 * when it has fi
37ec0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 nished using tha
37ed0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 t result..** ^If
37ee0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
37ef0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
37f00 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
37f10 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 nterfaces.** or
37f20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
37f30 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 lob is the speci
37f40 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 al constant SQLI
37f50 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 TE_TRANSIENT.**
37f60 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 then SQLite make
37f70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
37f80 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 result into spac
37f90 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a e obtained from.
37fa0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
37fb0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 _malloc()] befor
37fc0 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a e it returns..**
37fd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
37fe0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
37ff0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
38000 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 he result of.**
38010 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
38020 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
38030 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 6f 66 to be a copy of
38040 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 the.** [unprote
38050 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
38060 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 ue] object speci
38070 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 fied by the 2nd
38080 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 parameter. ^The
38090 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 .** sqlite3_resu
380a0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 lt_value() inter
380b0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 face makes a cop
380c0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 y of the [sqlite
380d0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 3_value].** so t
380e0 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hat the [sqlite3
380f0 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 _value] specifie
38100 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 d in the paramet
38110 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 er may change or
38120 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 .** be deallocat
38130 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 ed after sqlite3
38140 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
38150 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 returns without
38160 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f harm..** ^A [pro
38170 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
38180 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 alue] object may
38190 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 always be used
381a0 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 where an.** [unp
381b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
381c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 _value] object i
381d0 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 s required, so e
381e0 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 ither.** kind of
381f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
38200 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 object can be u
38210 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e sed with this in
38220 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 terface..**.** I
38230 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
38240 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d are called from
38250 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 within the diff
38260 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 erent thread.**
38270 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e than the one con
38280 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c taining the appl
38290 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
382a0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 function that re
382b0 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 ceived.** the [s
382c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 qlite3_context]
382d0 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 pointer, the res
382e0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
382f0 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ed..*/.SQLITE_AP
38300 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 I void SQLITE_ST
38310 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 DCALL sqlite3_re
38320 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 sult_blob(sqlite
38330 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
38340 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
38350 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 id(*)(void*));.S
38360 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 QLITE_API void S
38370 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
38380 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
38390 62 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 b64(sqlite3_cont
383a0 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ext*,const void*
383b0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
383c0 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c sql
383d0 69 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64 ite3_uint64,void
383e0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c (*)(void*));.SQL
383f0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c ITE_API void SQL
38400 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
38410 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c te3_result_doubl
38420 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
38430 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c t*, double);.SQL
38440 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c ITE_API void SQL
38450 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
38460 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
38470 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
38480 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 *, const char*,
38490 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
384a0 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 void SQLITE_STD
384b0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 CALL sqlite3_res
384c0 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 ult_error16(sqli
384d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
384e0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b nst void*, int);
384f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
38500 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
38510 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
38520 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 rror_toobig(sqli
38530 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 te3_context*);.S
38540 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 QLITE_API void S
38550 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
38560 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
38570 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 or_nomem(sqlite3
38580 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 _context*);.SQLI
38590 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 TE_API void SQLI
385a0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
385b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
385c0 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e code(sqlite3_con
385d0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c text*, int);.SQL
385e0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c ITE_API void SQL
385f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
38600 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 te3_result_int(s
38610 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
38620 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
38630 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 I void SQLITE_ST
38640 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 DCALL sqlite3_re
38650 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 sult_int64(sqlit
38660 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c e3_context*, sql
38670 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c ite3_int64);.SQL
38680 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c ITE_API void SQL
38690 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
386a0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 te3_result_null(
386b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
386c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
386d0 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c id SQLITE_STDCAL
386e0 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 L sqlite3_result
386f0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f _text(sqlite3_co
38700 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 ntext*, const ch
38710 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a ar*, int, void(*
38720 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
38730 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 E_API void SQLIT
38740 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
38750 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28 3_result_text64(
38760 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
38770 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 , const char*,sq
38780 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 lite3_uint64,.
38790 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
387a0 20 20 20 20 20 20 20 20 20 7