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 31 31 2e 31 22 0a 23 64 "3.11.1".#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 31 31 SION_NUMBER 3011
10d0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 001.#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 36 2d 30 33 2d 30 33 20 31 36 "2016-03-03 16
1100: 3a 31 37 3a 35 33 20 66 30 34 37 39 32 30 63 65 :17:53 f047920ce
1110: 31 36 39 37 31 65 35 37 33 62 63 36 65 63 39 61 16971e573bc6ec9a
1120: 34 38 62 31 31 38 63 39 64 65 32 62 33 61 37 22 48b118c9de2b3a7"
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 65 ader, and thus e
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 73 71 6c 69 74 65 33 5f r of.** sqlite3_
3ac0: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65 exec() after the
3ad0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
3ae0: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 tring is no long
3af0: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 er needed..** ^I
3b00: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 f the 5th parame
3b10: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3b20: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c xec() is not NUL
3b30: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a L and no errors.
3b40: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 ** occur, then s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 qlite3_exec() se
3b60: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 ts the pointer i
3b70: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 n its 5th parame
3b80: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 ter to.** NULL b
3b90: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e efore returning.
3ba0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 .**.** ^If an sq
3bb0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
3bc0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f lback returns no
3bd0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 n-zero, the sqli
3be0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f te3_exec().** ro
3bf0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 utine returns SQ
3c00: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f LITE_ABORT witho
3c10: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 ut invoking the
3c20: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 callback again a
3c30: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 nd.** without ru
3c40: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 nning any subseq
3c50: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 uent SQL stateme
3c60: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
3c70: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 2nd argument to
3c80: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 the sqlite3_exec
3c90: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 () callback func
3ca0: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e tion is the.** n
3cb0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
3cc0: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 in the result.
3cd0: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 ^The 3rd argume
3ce0: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
3cf0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 3_exec().** call
3d00: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 back is an array
3d10: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 of pointers to
3d20: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 strings obtained
3d30: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b as if from.** [
3d40: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
3d50: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 ext()], one for
3d60: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 each column. ^I
3d70: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 f an element of
3d80: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 a.** result row
3d90: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 is NULL then the
3da0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 corresponding s
3db0: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f tring pointer fo
3dc0: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 r the.** sqlite3
3dd0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
3de0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
3df0: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 er. ^The 4th ar
3e00: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a gument to the.**
3e10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3e20: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 callback is an a
3e30: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
3e40: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 to strings wher
3e50: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 e each.** entry
3e60: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e represents the n
3e70: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e ame of correspon
3e80: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 ding result colu
3e90: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a mn as obtained.*
3ea0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
3eb0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a column_name()]..
3ec0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e **.** ^If the 2n
3ed0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
3ee0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
3ef0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
3f00: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
3f10: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
3f20: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 , or a pointer t
3f30: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c hat contains onl
3f40: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 y whitespace and
3f50: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d /or .** SQL comm
3f60: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 ents, then no SQ
3f70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
3f80: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 evaluated and t
3f90: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 he database.** i
3fa0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a s not changed..*
3fb0: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e *.** Restriction
3fc0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
3fd0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 <li> The applic
3fe0: 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 ation must ensur
3ff0: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70 e that the 1st p
4000: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
4010: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 te3_exec().**
4020: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e is a valid an
4030: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 d open [database
4040: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
4050: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 <li> The applic
4060: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 ation must not c
4070: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 lose the [databa
4080: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 se connection] s
4090: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 pecified by.**
40a0: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61 the 1st para
40b0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
40c0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 _exec() while sq
40d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
40e0: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e running..** <li>
40f0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
4100: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 must not modify
4110: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
4120: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69 nt text passed i
4130: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 nto.** the
4140: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
4150: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
4160: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 while sqlite3_ex
4170: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e ec() is running.
4180: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c .** </ul>.*/.SQL
4190: 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
41a0: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
41b0: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 e3_exec(. sqlit
41c0: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 e3*,
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41e0: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e /* An open
41f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 database */. c
4200: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 onst char *sql,
4210: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4220: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c /* SQL
4230: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 to be evaluated
4240: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c */. int (*call
4250: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c back)(void*,int,
4260: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 char**,char**),
4270: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e /* Callback fun
4280: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 ction */. void
4290: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
42b0: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 /* 1st arg
42c0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 ument to callbac
42d0: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 k */. char **er
42e0: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 rmsg
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4300: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 /* Error msg w
4310: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 ritten here */.)
4320: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
4330: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a F: Result Codes.
4340: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 ** KEYWORDS: {re
4350: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 sult code defini
4360: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e tions}.**.** Man
4370: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f y SQLite functio
4380: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 ns return an int
4390: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 eger result code
43a0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 from the set sh
43b0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f own.** here in o
43c0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 rder to indicate
43d0: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c success or fail
43e0: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 ure..**.** New e
43f0: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 rror codes may b
4400: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
4410: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
4420: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 Lite..**.** See
4430: 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 also: [extended
4440: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 result code defi
4450: 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 nitions].*/.#def
4460: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 ine SQLITE_OK
4470: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 0 /* S
4480: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 uccessful result
4490: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 */./* beginning
44a0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 -of-error-codes
44b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
44c0: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 E_ERROR 1
44d0: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 /* SQL error
44e0: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 or missing datab
44f0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ase */.#define S
4500: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 QLITE_INTERNAL
4510: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 2 /* Intern
4520: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 al logic error i
4530: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 n SQLite */.#def
4540: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 ine SQLITE_PERM
4550: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 3 /* A
4560: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e ccess permission
4570: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 denied */.#defi
4580: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 ne SQLITE_ABORT
4590: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 4 /* Ca
45a0: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 llback routine r
45b0: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 equested an abor
45c0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
45d0: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 ITE_BUSY
45e0: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 5 /* The data
45f0: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 base file is loc
4600: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ked */.#define S
4610: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 QLITE_LOCKED
4620: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 6 /* A tabl
4630: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 e in the databas
4640: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 e is locked */.#
4650: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
4660: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f MEM 7 /
4670: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 * A malloc() fai
4680: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 led */.#define S
4690: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 QLITE_READONLY
46a0: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 8 /* Attemp
46b0: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 t to write a rea
46c0: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a donly database *
46d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
46e0: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 _INTERRUPT 9
46f0: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 /* Operation t
4700: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c erminated by sql
4710: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
4720: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4730: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 E_IOERR 10
4740: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 /* Some kind
4750: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f of disk I/O erro
4760: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 r occurred */.#d
4770: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 efine SQLITE_COR
4780: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a RUPT 11 /*
4790: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 The database di
47a0: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 sk image is malf
47b0: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ormed */.#define
47c0: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 SQLITE_NOTFOUND
47d0: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 12 /* Unkn
47e0: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 own opcode in sq
47f0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
4800: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ol() */.#define
4810: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 SQLITE_FULL
4820: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 13 /* Inser
4830: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 tion failed beca
4840: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20 use database is
4850: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 full */.#define
4860: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 SQLITE_CANTOPEN
4870: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 14 /* Unabl
4880: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 e to open the da
4890: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 tabase file */.#
48a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 define SQLITE_PR
48b0: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f OTOCOL 15 /
48c0: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 * Database lock
48d0: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a protocol error *
48e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
48f0: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 _EMPTY 16
4900: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 /* Database is
4910: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e empty */.#defin
4920: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 e SQLITE_SCHEMA
4930: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 17 /* The
4940: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 database schema
4950: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 changed */.#def
4960: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 ine SQLITE_TOOBI
4970: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 G 18 /* S
4980: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 tring or BLOB ex
4990: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 ceeds size limit
49a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
49b0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 TE_CONSTRAINT 1
49c0: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 9 /* Abort due
49d0: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 to constraint v
49e0: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 iolation */.#def
49f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 ine SQLITE_MISMA
4a00: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 TCH 20 /* D
4a10: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 ata type mismatc
4a20: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c h */.#define SQL
4a30: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 ITE_MISUSE
4a40: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 21 /* Library
4a50: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 used incorrectly
4a60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4a70: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 TE_NOLFS 2
4a80: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 2 /* Uses OS f
4a90: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 eatures not supp
4aa0: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f orted on host */
4ab0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4ac0: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 AUTH 23
4ad0: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f /* Authorizatio
4ae0: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 n denied */.#def
4af0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 ine SQLITE_FORMA
4b00: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 T 24 /* A
4b10: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 uxiliary databas
4b20: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a e format error *
4b30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4b40: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 _RANGE 25
4b50: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 /* 2nd paramet
4b60: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 er to sqlite3_bi
4b70: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 nd out of range
4b80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4b90: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 E_NOTADB 26
4ba0: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 /* File opene
4bb0: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 d that is not a
4bc0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f database file */
4bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4be0: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20 NOTICE 27
4bf0: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e /* Notification
4c00: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c s from sqlite3_l
4c10: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 og() */.#define
4c20: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 SQLITE_WARNING
4c30: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 28 /* Warni
4c40: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ngs from sqlite3
4c50: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e _log() */.#defin
4c60: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 e SQLITE_ROW
4c70: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 100 /* sql
4c80: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 ite3_step() has
4c90: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 another row read
4ca0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
4cb0: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 ITE_DONE
4cc0: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 101 /* sqlite3_
4cd0: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 step() has finis
4ce0: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f hed executing */
4cf0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 ./* end-of-error
4d00: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a -codes */../*.**
4d10: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e CAPI3REF: Exten
4d20: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 ded Result Codes
4d30: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 .** KEYWORDS: {e
4d40: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
4d50: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d ode definitions}
4d60: 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 .**.** In its de
4d70: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
4d80: 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 ion, SQLite API
4d90: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
4da0: 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 one of 30 intege
4db0: 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 r.** [result cod
4dc0: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 es]. However, e
4dd0: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 xperience has sh
4de0: 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 own that many of
4df0: 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 .** these result
4e00: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 codes are too c
4e10: 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 oarse-grained.
4e20: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 They do not prov
4e30: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 ide as.** much i
4e40: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
4e50: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f problems as pro
4e60: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c grammers might l
4e70: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f ike. In an effo
4e80: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 rt to.** address
4e90: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 this, newer ver
4ea0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
4eb0: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 (version 3.3.8 a
4ec0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 nd later) includ
4ed0: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 e.** support for
4ee0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 additional resu
4ef0: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 lt codes that pr
4f00: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 ovide more detai
4f10: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a led information.
4f20: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e ** about errors.
4f30: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 These [extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 result codes] a
4f50: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 re enabled or di
4f60: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 sabled.** on a p
4f70: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e er database conn
4f80: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 ection basis usi
4f90: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
4fa0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
4fb0: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e lt_codes()] API.
4fc0: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 Or, the extend
4fd0: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 ed code for.** t
4fe0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 he most recent e
4ff0: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 rror can be obta
5000: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 ined using.** [s
5010: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
5020: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 errcode()]..*/.#
5030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5040: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 ERR_READ
5050: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5060: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 ERR | (1<<8)).#d
5070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5080: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 RR_SHORT_READ
5090: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
50a0: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 RR | (2<<8)).#de
50b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
50c0: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 R_WRITE
50d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
50e0: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 R | (3<<8)).#def
50f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5100: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 _FSYNC
5110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5120: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 | (4<<8)).#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5140: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 DIR_FSYNC
5150: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5160: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (5<<8)).#defin
5170: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 e SQLITE_IOERR_T
5180: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 RUNCATE
5190: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
51a0: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (6<<8)).#define
51b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 SQLITE_IOERR_FS
51c0: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 TAT
51d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
51e0: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (7<<8)).#define
51f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c SQLITE_IOERR_UNL
5200: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 OCK (
5210: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5220: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 8<<8)).#define S
5230: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f QLITE_IOERR_RDLO
5240: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 CK (S
5250: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 QLITE_IOERR | (9
5260: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5270: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 LITE_IOERR_DELET
5280: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 E (SQ
5290: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 LITE_IOERR | (10
52a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
52b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
52c0: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 ED (SQ
52d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 LITE_IOERR | (11
52e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
52f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d LITE_IOERR_NOMEM
5300: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
5310: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 LITE_IOERR | (12
5320: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5330: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 LITE_IOERR_ACCES
5340: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 S (SQ
5350: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 LITE_IOERR | (13
5360: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5370: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b LITE_IOERR_CHECK
5380: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 RESERVEDLOCK (SQ
5390: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 LITE_IOERR | (14
53a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
53b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 LITE_IOERR_LOCK
53c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
53d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 LITE_IOERR | (15
53e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
53f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 LITE_IOERR_CLOSE
5400: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
5410: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 LITE_IOERR | (16
5420: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5430: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 LITE_IOERR_DIR_C
5440: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 LOSE (SQ
5450: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 LITE_IOERR | (17
5460: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5470: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 LITE_IOERR_SHMOP
5480: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 EN (SQ
5490: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 LITE_IOERR | (18
54a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
54b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 LITE_IOERR_SHMSI
54c0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 ZE (SQ
54d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 LITE_IOERR | (19
54e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
54f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f LITE_IOERR_SHMLO
5500: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 CK (SQ
5510: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 LITE_IOERR | (20
5520: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5530: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 LITE_IOERR_SHMMA
5540: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 P (SQ
5550: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 LITE_IOERR | (21
5560: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5570: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 LITE_IOERR_SEEK
5580: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
5590: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 LITE_IOERR | (22
55a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
55b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 LITE_IOERR_DELET
55c0: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 E_NOENT (SQ
55d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 LITE_IOERR | (23
55e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
55f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 LITE_IOERR_MMAP
5600: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
5610: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 LITE_IOERR | (24
5620: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5630: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 LITE_IOERR_GETTE
5640: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51 MPPATH (SQ
5650: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 LITE_IOERR | (25
5660: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5670: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 LITE_IOERR_CONVP
5680: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51 ATH (SQ
5690: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 LITE_IOERR | (26
56a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
56b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 LITE_IOERR_VNODE
56c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
56d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 LITE_IOERR | (27
56e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
56f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 LITE_IOERR_AUTH
5700: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
5710: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 LITE_IOERR | (28
5720: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5730: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 LITE_LOCKED_SHAR
5740: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 EDCACHE (SQ
5750: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 LITE_LOCKED | (
5760: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5770: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 QLITE_BUSY_RECOV
5780: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 ERY (S
5790: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 QLITE_BUSY |
57a0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
57b0: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 SQLITE_BUSY_SNAP
57c0: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 SHOT (
57d0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 SQLITE_BUSY |
57e0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
57f0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
5800: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 _NOTEMPDIR
5810: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e (SQLITE_CANTOPEN
5820: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
5830: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 ne SQLITE_CANTOP
5840: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 EN_ISDIR
5850: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 (SQLITE_CANTOP
5860: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 EN | (2<<8)).#de
5870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 fine SQLITE_CANT
5880: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 OPEN_FULLPATH
5890: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 (SQLITE_CANT
58a0: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 OPEN | (3<<8)).#
58b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
58c0: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 NTOPEN_CONVPATH
58d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
58e0: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 NTOPEN | (4<<8))
58f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5900: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 CORRUPT_VTAB
5910: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5920: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 CORRUPT | (1<<8)
5930: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5940: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 _READONLY_RECOVE
5950: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 RY (SQLITE
5960: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c _READONLY | (1<<
5970: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5980: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 TE_READONLY_CANT
5990: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 LOCK (SQLI
59a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 TE_READONLY | (2
59b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
59c0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f LITE_READONLY_RO
59d0: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 LLBACK (SQ
59e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 LITE_READONLY |
59f0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (3<<8)).#define
5a00: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f SQLITE_READONLY_
5a10: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 DBMOVED (
5a20: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
5a30: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (4<<8)).#defin
5a40: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 e SQLITE_ABORT_R
5a50: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 OLLBACK
5a60: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c (SQLITE_ABORT |
5a70: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
5a80: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5a90: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 NT_CHECK
5aa0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5ab0: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 NT | (1<<8)).#de
5ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5ad0: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f TRAINT_COMMITHOO
5ae0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 K (SQLITE_CONS
5af0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 TRAINT | (2<<8))
5b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5b10: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 CONSTRAINT_FOREI
5b20: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f GNKEY (SQLITE_
5b30: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c CONSTRAINT | (3<
5b40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5b50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 ITE_CONSTRAINT_F
5b60: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c UNCTION (SQL
5b70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5b80: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (4<<8)).#define
5b90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5ba0: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 NT_NOTNULL
5bb0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5bc0: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 NT | (5<<8)).#de
5bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5be0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 TRAINT_PRIMARYKE
5bf0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 Y (SQLITE_CONS
5c00: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 TRAINT | (6<<8))
5c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5c20: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 CONSTRAINT_TRIGG
5c30: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f ER (SQLITE_
5c40: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c CONSTRAINT | (7<
5c50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5c60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 ITE_CONSTRAINT_U
5c70: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c NIQUE (SQL
5c80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5c90: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (8<<8)).#define
5ca0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5cb0: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 NT_VTAB
5cc0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5cd0: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 NT | (9<<8)).#de
5ce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5cf0: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 TRAINT_ROWID
5d00: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
5d10: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 TRAINT |(10<<8))
5d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5d30: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 NOTICE_RECOVER_W
5d40: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f AL (SQLITE_
5d50: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 NOTICE | (1<<8))
5d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5d70: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 NOTICE_RECOVER_R
5d80: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f OLLBACK (SQLITE_
5d90: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 NOTICE | (2<<8))
5da0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5db0: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 WARNING_AUTOINDE
5dc0: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f X (SQLITE_
5dd0: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 WARNING | (1<<8)
5de0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5df0: 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 _AUTH_USER
5e00: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5e10: 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a _AUTH | (1<<8)).
5e20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
5e30: 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 Flags For File
5e40: 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a Open Operations.
5e50: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 **.** These bit
5e60: 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e values are inten
5e70: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 ded for use in t
5e80: 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 he.** 3rd parame
5e90: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ter to the [sqli
5ea0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 te3_open_v2()] i
5eb0: 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 nterface and.**
5ec0: 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d in the 4th param
5ed0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c eter to the [sql
5ee0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 ite3_vfs.xOpen]
5ef0: 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 method..*/.#defi
5f00: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 ne SQLITE_OPEN_R
5f10: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 EADONLY
5f20: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 0x00000001 /* O
5f30: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
5f40: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
5f50: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 ne SQLITE_OPEN_R
5f60: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20 EADWRITE
5f70: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 0x00000002 /* O
5f80: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
5f90: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
5fa0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 ne SQLITE_OPEN_C
5fb0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20 REATE
5fc0: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 0x00000004 /* O
5fd0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
5fe0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
5ff0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 ne SQLITE_OPEN_D
6000: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 ELETEONCLOSE
6010: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 0x00000008 /* V
6020: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
6030: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 ne SQLITE_OPEN_E
6040: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 XCLUSIVE
6050: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 0x00000010 /* V
6060: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
6070: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 ne SQLITE_OPEN_A
6080: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 UTOPROXY
6090: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 0x00000020 /* V
60a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
60b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 ne SQLITE_OPEN_U
60c0: 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20 20 RI
60d0: 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 0x00000040 /* O
60e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
60f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
6100: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
6110: 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20 20 EMORY
6120: 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 0x00000080 /* O
6130: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
6140: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
6150: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
6160: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 AIN_DB
6170: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 0x00000100 /* V
6180: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
6190: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
61a0: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 EMP_DB
61b0: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 0x00000200 /* V
61c0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
61d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
61e0: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 RANSIENT_DB
61f0: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 0x00000400 /* V
6200: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
6210: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
6220: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 AIN_JOURNAL
6230: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 0x00000800 /* V
6240: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
6250: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
6260: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 EMP_JOURNAL
6270: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 0x00001000 /* V
6280: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
6290: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 ne SQLITE_OPEN_S
62a0: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 UBJOURNAL
62b0: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 0x00002000 /* V
62c0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
62d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
62e0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 ASTER_JOURNAL
62f0: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 0x00004000 /* V
6300: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
6310: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e ne SQLITE_OPEN_N
6320: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20 OMUTEX
6330: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 0x00008000 /* O
6340: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
6350: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
6360: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 ne SQLITE_OPEN_F
6370: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 ULLMUTEX
6380: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 0x00010000 /* O
6390: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
63a0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
63b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 ne SQLITE_OPEN_S
63c0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 HAREDCACHE
63d0: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 0x00020000 /* O
63e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
63f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
6400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 ne SQLITE_OPEN_P
6410: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20 RIVATECACHE
6420: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 0x00040000 /* O
6430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
6440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
6450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 ne SQLITE_OPEN_W
6460: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AL
6470: 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 0x00080000 /* V
6480: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 FS only */../* R
6490: 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 eserved:
64a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
64b0: 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 0x00F00000 */..
64c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
64d0: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 Device Character
64e0: 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 istics.**.** The
64f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 xDeviceCharacte
6500: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f ristics method o
6510: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 f the [sqlite3_i
6520: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 o_methods].** ob
6530: 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 ject returns an
6540: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 integer which is
6550: 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 a vector of the
6560: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 se.** bit values
6570: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 expressing I/O
6580: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 characteristics
6590: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 of the mass stor
65a0: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 age.** device th
65b0: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c at holds the fil
65c0: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 e that the [sqli
65d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a te3_io_methods].
65e0: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a ** refers to..**
65f0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 .** The SQLITE_I
6600: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 OCAP_ATOMIC prop
6610: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 erty means that
6620: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a all writes of.**
6630: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 any size are at
6640: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
6650: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e E_IOCAP_ATOMICnn
6660: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e n values.** mean
6670: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 that writes of
6680: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 blocks that are
6690: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a nnn bytes in siz
66a0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 e and.** are ali
66b0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 gned to an addre
66c0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 ss which is an i
66d0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 nteger multiple
66e0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 of.** nnn are at
66f0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
6700: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
6710: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a END value means.
6720: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 ** that when dat
6730: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f a is appended to
6740: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 a file, the dat
6750: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a a is appended.**
6760: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 first then the
6770: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 size of the file
6780: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 is extended, ne
6790: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a ver the other.**
67a0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 way around. Th
67b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
67c0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 EQUENTIAL proper
67d0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a ty means that.**
67e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
67f0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 written to disk
6800: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 in the same orde
6810: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f r as calls.** to
6820: 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 xWrite(). The
6830: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 SQLITE_IOCAP_POW
6840: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
6850: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 property means
6860: 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 that.** after re
6870: 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 boot following a
6880: 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 crash or power
6890: 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 loss, the only b
68a0: 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c ytes in a.** fil
68b0: 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74 e that were writ
68c0: 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 ten at the appli
68d0: 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 cation level mig
68e0: 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a ht have changed.
68f0: 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 ** and that adja
6900: 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e cent bytes, even
6910: 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 bytes within th
6920: 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 e same sector ar
6930: 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 e.** guaranteed
6940: 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e to be unchanged.
6950: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
6960: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 AP_UNDELETABLE_W
6970: 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 HEN_OPEN.** flag
6980: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 61 indicate that a
6990: 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 file cannot be
69a0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65 deleted when ope
69b0: 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 n. The.** SQLIT
69c0: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c E_IOCAP_IMMUTABL
69d0: 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 E flag indicates
69e0: 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 20 69 that the file i
69f0: 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c s on.** read-onl
6a00: 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e 6e y media and cann
6a10: 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 65 76 ot be changed ev
6a20: 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73 20 en by processes
6a30: 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 with.** elevated
6a40: 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a privileges..*/.
6a50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6a60: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 OCAP_ATOMIC
6a70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6a80: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 000001.#define S
6a90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6aa0: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 IC512
6ab0: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 0x00000002.#d
6ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
6ad0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 AP_ATOMIC1K
6ae0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
6af0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 0004.#define SQL
6b00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
6b10: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2K
6b20: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 0x00000008.#def
6b30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6b40: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 _ATOMIC4K
6b50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6b60: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 10.#define SQLIT
6b70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b E_IOCAP_ATOMIC8K
6b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
6b90: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e x00000020.#defin
6ba0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6bb0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 TOMIC16K
6bc0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
6bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6be0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 IOCAP_ATOMIC32K
6bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6c00: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 0000080.#define
6c10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6c20: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 MIC64K
6c30: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 0x00000100.#
6c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6c50: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
6c60: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6c70: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00200.#define SQ
6c80: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
6c90: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 NTIAL
6ca0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 0x00000400.#de
6cb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6cc0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 P_UNDELETABLE_WH
6cd0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 EN_OPEN 0x00000
6ce0: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 800.#define SQLI
6cf0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
6d00: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 FE_OVERWRITE
6d10: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 0x00001000.#defi
6d20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6d30: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 IMMUTABLE
6d40: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 0x0000200
6d50: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
6d60: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 F: File Locking
6d70: 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c Levels.**.** SQL
6d80: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 ite uses one of
6d90: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 these integer va
6da0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f lues as the seco
6db0: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 nd.** argument t
6dc0: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 o calls it makes
6dd0: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 to the xLock()
6de0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 and xUnlock() me
6df0: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b thods.** of an [
6e00: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
6e10: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 ds] object..*/.#
6e20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
6e30: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 CK_NONE
6e40: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
6e50: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 E_LOCK_SHARED
6e60: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
6e70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
6e80: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 VED 2.#defi
6e90: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 ne SQLITE_LOCK_P
6ea0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 ENDING 3.#
6eb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
6ec0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 CK_EXCLUSIVE
6ed0: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 4../*.** CAPI3R
6ee0: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 EF: Synchronizat
6ef0: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a ion Type Flags.*
6f00: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 *.** When SQLite
6f10: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 invokes the xSy
6f20: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 nc() method of a
6f30: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f n.** [sqlite3_io
6f40: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
6f50: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 it uses a combi
6f60: 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 nation of.** the
6f70: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 se integer value
6f80: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 s as the second
6f90: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
6fa0: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f When the SQLITE_
6fb0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c SYNC_DATAONLY fl
6fc0: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d ag is used, it m
6fd0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a eans that the.**
6fe0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 sync operation
6ff0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c only needs to fl
7000: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 ush data to mass
7010: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 storage. Inode
7020: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
7030: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 need not be flus
7040: 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 hed. If the lowe
7050: 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 r four bits of t
7060: 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c he flag.** equal
7070: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 SQLITE_SYNC_NOR
7080: 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 MAL, that means
7090: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 to use normal fs
70a0: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e ync() semantics.
70b0: 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 .** If the lower
70c0: 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c four bits equal
70d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
70e0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a L, that means.**
70f0: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 to use Mac OS X
7100: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 style fullsync
7110: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 instead of fsync
7120: 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 ()..**.** Do not
7130: 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c confuse the SQL
7140: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 ITE_SYNC_NORMAL
7150: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f and SQLITE_SYNC_
7160: 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 FULL flags.** wi
7170: 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 th the [PRAGMA s
7180: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d ynchronous]=NORM
7190: 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 AL and [PRAGMA s
71a0: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c ynchronous]=FULL
71b0: 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 .** settings. T
71c0: 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 he [synchronous
71d0: 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e pragma] determin
71e0: 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f es when calls to
71f0: 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 the.** xSync VF
7200: 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 S method occur a
7210: 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f nd applies unifo
7220: 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 rmly across all
7230: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 platforms..** Th
7240: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f e SQLITE_SYNC_NO
7250: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f RMAL and SQLITE_
7260: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 SYNC_FULL flags
7270: 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a determine how.**
7280: 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 energetic or ri
7290: 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 gorous or forcef
72a0: 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 ul the sync oper
72b0: 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a ations are and.*
72c0: 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 * only make a di
72d0: 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 fference on Mac
72e0: 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 OSX for the defa
72f0: 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e ult SQLite code.
7300: 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 .** (Third-party
7310: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
7320: 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 ions might also
7330: 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 make the distinc
7340: 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 tion.** between
7350: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
7360: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 AL and SQLITE_SY
7370: 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f NC_FULL, but amo
7380: 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 ng the.** operat
7390: 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 ing systems nati
73a0: 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 vely supported b
73b0: 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d y SQLite, only M
73c0: 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 ac OSX.** cares
73d0: 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 about the differ
73e0: 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e ence.).*/.#defin
73f0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f e SQLITE_SYNC_NO
7400: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 RMAL 0x00
7410: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 002.#define SQLI
7420: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 TE_SYNC_FULL
7430: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 0x00003.#d
7440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
7450: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 C_DATAONLY
7460: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 0x00010../*.** C
7470: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 API3REF: OS Inte
7480: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 rface Open File
7490: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 Handle.**.** An
74a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
74b0: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 bject represents
74c0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e an open file in
74d0: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 the .** [sqlite
74e0: 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 3_vfs | OS inter
74f0: 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e face layer]. In
7500: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 dividual OS inte
7510: 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 rface.** impleme
7520: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a ntations will.**
7530: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 want to subclas
7540: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 s this object by
7550: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 appending addit
7560: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 ional fields.**
7570: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 for their own us
7580: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 e. The pMethods
7590: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e entry is a poin
75a0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 ter to an.** [sq
75b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
75c0: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 ] object that de
75d0: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f fines methods fo
75e0: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 r performing.**
75f0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f I/O operations o
7600: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e n the open file.
7610: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
7620: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 ct sqlite3_file
7630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 sqlite3_file;.st
7640: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c ruct sqlite3_fil
7650: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 e {. const stru
7660: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
7670: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b thods *pMethods;
7680: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 /* Methods for
7690: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f an open file */
76a0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
76b0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
76c0: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d e File Virtual M
76d0: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a ethods Object.**
76e0: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f .** Every file o
76f0: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 pened by the [sq
7700: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
7710: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 method populate
7720: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s an.** [sqlite3
7730: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f _file] object (o
7740: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 r, more commonly
7750: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 , a subclass of
7760: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
7770: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 file] object) wi
7780: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 th a pointer to
7790: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
77a0: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 his object..** T
77b0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e his object defin
77c0: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 es the methods u
77d0: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 sed to perform v
77e0: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e arious operation
77f0: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 s.** against the
7800: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 open file repre
7810: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 sented by the [s
7820: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
7830: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ect..**.** If th
7840: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
7850: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 Open] method set
7860: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 s the sqlite3_fi
7870: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d le.pMethods elem
7880: 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e ent .** to a non
7890: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 -NULL pointer, t
78a0: 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hen the sqlite3_
78b0: 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 io_methods.xClos
78c0: 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 e method.** may
78d0: 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 be invoked even
78e0: 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f if the [sqlite3_
78f0: 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 vfs.xOpen] repor
7900: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c ted that it fail
7910: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 ed. The.** only
7920: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 way to prevent
7930: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 a call to xClose
7940: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 following a fai
7950: 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 led [sqlite3_vfs
7960: 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f .xOpen].** is fo
7970: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 r the [sqlite3_v
7980: 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 fs.xOpen] to set
7990: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c the sqlite3_fil
79a0: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 e.pMethods eleme
79b0: 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a nt.** to NULL..*
79c0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 *.** The flags a
79d0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 rgument to xSync
79e0: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b may be one of [
79f0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
7a00: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 AL] or.** [SQLIT
7a10: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 E_SYNC_FULL]. T
7a20: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 he first choice
7a30: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 is the normal fs
7a40: 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 ync()..** The se
7a50: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 cond choice is a
7a60: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 Mac OS X style
7a70: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b fullsync. The [
7a80: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
7a90: 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 ONLY].** flag ma
7aa0: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 y be ORed in to
7ab0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e indicate that on
7ac0: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 ly the data of t
7ad0: 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e he file.** and n
7ae0: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 ot its inode nee
7af0: 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e ds to be synced.
7b00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 .**.** The integ
7b10: 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f er values to xLo
7b20: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b ck() and xUnlock
7b30: 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a () are one of.**
7b40: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
7b50: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d QLITE_LOCK_NONE]
7b60: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ,.** <li> [SQLIT
7b70: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a E_LOCK_SHARED],.
7b80: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
7b90: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a LOCK_RESERVED],.
7ba0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
7bb0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f LOCK_PENDING], o
7bc0: 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 r.** <li> [SQLIT
7bd0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
7be0: 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 ]..** </ul>.** x
7bf0: 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 Lock() increases
7c00: 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f the lock. xUnlo
7c10: 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 ck() decreases t
7c20: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 he lock..** The
7c30: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f xCheckReservedLo
7c40: 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 ck() method chec
7c50: 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 ks whether any d
7c60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
7c70: 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e on,.** either in
7c80: 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 this process or
7c90: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 in some other p
7ca0: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 rocess, is holdi
7cb0: 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a ng a RESERVED,.*
7cc0: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 * PENDING, or EX
7cd0: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 CLUSIVE lock on
7ce0: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 the file. It re
7cf0: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 turns true.** if
7d00: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 such a lock exi
7d10: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 sts and false ot
7d20: 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 herwise..**.** T
7d30: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 he xFileControl(
7d40: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 ) method is a ge
7d50: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 neric interface
7d60: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 that allows cust
7d70: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d om.** VFS implem
7d80: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 entations to dir
7d90: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e ectly control an
7da0: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 open file using
7db0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
7dc0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
7dd0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 interface. The
7de0: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 second "op" arg
7df0: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 ument is an.** i
7e00: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 nteger opcode.
7e10: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
7e20: 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 nt is a generic
7e30: 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 pointer intended
7e40: 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 to.** point to
7e50: 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 a structure that
7e60: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 may contain arg
7e70: 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 uments or space
7e80: 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 in which to.** w
7e90: 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 rite return valu
7ea0: 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 es. Potential u
7eb0: 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e ses for xFileCon
7ec0: 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a trol() might be.
7ed0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 ** functions to
7ee0: 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 enable blocking
7ef0: 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f locks with timeo
7f00: 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 uts, to change t
7f10: 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 he.** locking st
7f20: 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d rategy (for exam
7f30: 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 ple to use dot-f
7f40: 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 ile locks), to i
7f50: 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 nquire.** about
7f60: 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 the status of a
7f70: 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 lock, or to brea
7f80: 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 k stale locks.
7f90: 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f The SQLite.** co
7fa0: 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 re reserves all
7fb0: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 opcodes less tha
7fc0: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 n 100 for its ow
7fd0: 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c n use..** A [fil
7fe0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 e control opcode
7ff0: 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f s | list of opco
8000: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 des] less than 1
8010: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 00 is available.
8020: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 .** Applications
8030: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 that define a c
8040: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 ustom xFileContr
8050: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 ol method should
8060: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 use opcodes.**
8070: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 greater than 100
8080: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 to avoid confli
8090: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d cts. VFS implem
80a0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 entations should
80b0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
80c0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 TE_NOTFOUND] for
80d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 file control op
80e0: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20 codes that they
80f0: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e do not.** recogn
8100: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ize..**.** The x
8110: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 SectorSize() met
8120: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 hod returns the
8130: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 sector size of t
8140: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 he.** device tha
8150: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 t underlies the
8160: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f file. The secto
8170: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a r size is the.**
8180: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 minimum write t
8190: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f hat can be perfo
81a0: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 rmed without dis
81b0: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 turbing.** other
81c0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 bytes in the fi
81d0: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 le. The xDevice
81e0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 Characteristics(
81f0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 ).** method retu
8200: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 rns a bit vector
8210: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 describing beha
8220: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 viors of the.**
8230: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 underlying devic
8240: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a e:.**.** <ul>.**
8250: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
8260: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c CAP_ATOMIC].** <
8270: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
8280: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 P_ATOMIC512].**
8290: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
82a0: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 AP_ATOMIC1K].**
82b0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
82c0: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 AP_ATOMIC2K].**
82d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
82e0: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 AP_ATOMIC4K].**
82f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
8300: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 AP_ATOMIC8K].**
8310: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
8320: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a AP_ATOMIC16K].**
8330: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
8340: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a CAP_ATOMIC32K].*
8350: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
8360: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a OCAP_ATOMIC64K].
8370: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8380: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e IOCAP_SAFE_APPEN
8390: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 D].** <li> [SQLI
83a0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
83b0: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a IAL].** </ul>.**
83c0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 .** The SQLITE_I
83d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 OCAP_ATOMIC prop
83e0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 erty means that
83f0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a all writes of.**
8400: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 any size are at
8410: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
8420: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e E_IOCAP_ATOMICnn
8430: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e n values.** mean
8440: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 that writes of
8450: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 blocks that are
8460: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a nnn bytes in siz
8470: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 e and.** are ali
8480: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 gned to an addre
8490: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 ss which is an i
84a0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 nteger multiple
84b0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 of.** nnn are at
84c0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
84d0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
84e0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a END value means.
84f0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 ** that when dat
8500: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f a is appended to
8510: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 a file, the dat
8520: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a a is appended.**
8530: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 first then the
8540: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 size of the file
8550: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 is extended, ne
8560: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a ver the other.**
8570: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 way around. Th
8580: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
8590: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 EQUENTIAL proper
85a0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a ty means that.**
85b0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
85c0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 written to disk
85d0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 in the same orde
85e0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f r as calls.** to
85f0: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a xWrite()..**.**
8600: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 If xRead() retu
8610: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 rns SQLITE_IOERR
8620: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d _SHORT_READ it m
8630: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a ust also fill.**
8640: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 in the unread p
8650: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 ortions of the b
8660: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 uffer with zeros
8670: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a . A VFS that.**
8680: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 fails to zero-f
8690: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 ill short reads
86a0: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f might seem to wo
86b0: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a rk. However,.**
86c0: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f failure to zero
86d0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 -fill short read
86e0: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c s will eventuall
86f0: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 y lead to.** dat
8700: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e abase corruption
8710: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
8720: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d uct sqlite3_io_m
8730: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 ethods sqlite3_i
8740: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 o_methods;.struc
8750: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 t sqlite3_io_met
8760: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 hods {. int iVe
8770: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 rsion;. int (*x
8780: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 Close)(sqlite3_f
8790: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ile*);. int (*x
87a0: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 Read)(sqlite3_fi
87b0: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 le*, void*, int
87c0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e iAmt, sqlite3_in
87d0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e t64 iOfst);. in
87e0: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 t (*xWrite)(sqli
87f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 te3_file*, const
8800: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 void*, int iAmt
8810: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
8820: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a iOfst);. int (*
8830: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 xTruncate)(sqlit
8840: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 e3_file*, sqlite
8850: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 3_int64 size);.
8860: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 int (*xSync)(sq
8870: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
8880: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 flags);. int (
8890: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 *xFileSize)(sqli
88a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
88b0: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 e3_int64 *pSize)
88c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 ;. int (*xLock)
88d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
88e0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 int);. int (*xU
88f0: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 nlock)(sqlite3_f
8900: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ile*, int);. in
8910: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 t (*xCheckReserv
8920: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f edLock)(sqlite3_
8930: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 file*, int *pRes
8940: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 Out);. int (*xF
8950: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 ileControl)(sqli
8960: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f te3_file*, int o
8970: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a p, void *pArg);.
8980: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 int (*xSectorS
8990: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ize)(sqlite3_fil
89a0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 e*);. int (*xDe
89b0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
89c0: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ics)(sqlite3_fil
89d0: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 e*);. /* Method
89e0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 s above are vali
89f0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 d for version 1
8a00: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d */. int (*xShmM
8a10: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ap)(sqlite3_file
8a20: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 *, int iPg, int
8a30: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 pgsz, int, void
8a40: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 volatile**);. i
8a50: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 nt (*xShmLock)(s
8a60: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
8a70: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c t offset, int n,
8a80: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 int flags);. v
8a90: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 oid (*xShmBarrie
8aa0: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a r)(sqlite3_file*
8ab0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 );. int (*xShmU
8ac0: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 nmap)(sqlite3_fi
8ad0: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 le*, int deleteF
8ae0: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f lag);. /* Metho
8af0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c ds above are val
8b00: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 id for version 2
8b10: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 */. int (*xFet
8b20: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ch)(sqlite3_file
8b30: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
8b40: 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 iOfst, int iAmt
8b50: 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 , void **pp);.
8b60: 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 int (*xUnfetch)(
8b70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
8b80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
8b90: 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 st, void *p);.
8ba0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 /* Methods above
8bb0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 are valid for v
8bc0: 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a ersion 3 */. /*
8bd0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 Additional meth
8be0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ods may be added
8bf0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
8c00: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a ses */.};../*.**
8c10: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 CAPI3REF: Stand
8c20: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c ard File Control
8c30: 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 Opcodes.** KEYW
8c40: 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 ORDS: {file cont
8c50: 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 rol opcodes} {fi
8c60: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 le control opcod
8c70: 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 e}.**.** These i
8c80: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
8c90: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 are opcodes for
8ca0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
8cb0: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 l method.** of t
8cc0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d he [sqlite3_io_m
8cd0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 ethods] object a
8ce0: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 nd for the [sqli
8cf0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
8d00: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
8d10: 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 ..**.** <ul>.**
8d20: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
8d30: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a TL_LOCKSTATE]].*
8d40: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
8d50: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f NTL_LOCKSTATE] o
8d60: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f pcode is used fo
8d70: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 r debugging. Th
8d80: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 is.** opcode cau
8d90: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e ses the xFileCon
8da0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 trol method to w
8db0: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 rite the current
8dc0: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 state of.** the
8dd0: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 lock (one of [S
8de0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d QLITE_LOCK_NONE]
8df0: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 , [SQLITE_LOCK_S
8e00: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 HARED],.** [SQLI
8e10: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 TE_LOCK_RESERVED
8e20: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ], [SQLITE_LOCK_
8e30: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 PENDING], or [SQ
8e40: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
8e50: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e IVE]).** into an
8e60: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 integer that th
8e70: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 e pArg argument
8e80: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 points to. This
8e90: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 capability.** is
8ea0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 used during tes
8eb0: 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 ting and is only
8ec0: 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 available when
8ed0: 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a the SQLITE_TEST.
8ee0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ** compile-time
8ef0: 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a option is used..
8f00: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
8f10: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 TE_FCNTL_SIZE_HI
8f20: 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c NT]].** The [SQL
8f30: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 ITE_FCNTL_SIZE_H
8f40: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 INT] opcode is u
8f50: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f sed by SQLite to
8f60: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a give the VFS.**
8f70: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 layer a hint of
8f80: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 how large the d
8f90: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c atabase file wil
8fa0: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 l grow to be dur
8fb0: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 ing the.** curre
8fc0: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 nt transaction.
8fd0: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f This hint is no
8fe0: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 t guaranteed to
8ff0: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 be accurate but
9000: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 it.** is often c
9010: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 lose. The under
9020: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 lying VFS might
9030: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c choose to preall
9040: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a ocate database.*
9050: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 * file space bas
9060: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 ed on this hint
9070: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 in order to help
9080: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 writes to the d
9090: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 atabase.** file
90a0: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a run faster..**.*
90b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
90c0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d CNTL_CHUNK_SIZE]
90d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
90e0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a _FCNTL_CHUNK_SIZ
90f0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
9100: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 d to request tha
9110: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 t the VFS.** ext
9120: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 ends and truncat
9130: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
9140: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f file in chunks o
9150: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 f a size specifi
9160: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 ed.** by the use
9170: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 r. The fourth ar
9180: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 gument to [sqlit
9190: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
91a0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f )] should .** po
91b0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 int to an intege
91c0: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e r (type int) con
91d0: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 taining the new
91e0: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 chunk-size to us
91f0: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d e.** for the nom
9200: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e inated database.
9210: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 Allocating data
9220: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 base file space
9230: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e in large.** chun
9240: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 ks (say 1MB at a
9250: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 time), may redu
9260: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 ce file-system f
9270: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 ragmentation and
9280: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 .** improve perf
9290: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 ormance on some
92a0: 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c systems..**.** <
92b0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
92c0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d L_FILE_POINTER]]
92d0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
92e0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 FCNTL_FILE_POINT
92f0: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 ER] opcode is us
9300: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 ed to obtain a p
9310: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
9320: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
9330: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 object associate
9340: 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 d with a particu
9350: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 lar database.**
9360: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 connection. See
9370: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 also [SQLITE_FC
9380: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e NTL_JOURNAL_POIN
9390: 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e TER]..**.** <li>
93a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a [[SQLITE_FCNTL_J
93b0: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d OURNAL_POINTER]]
93c0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
93d0: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f FCNTL_JOURNAL_PO
93e0: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 INTER] opcode is
93f0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 used to obtain
9400: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
9410: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
9420: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 e] object associ
9430: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a 6f ated with the jo
9440: 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 68 urnal file (eith
9450: 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 er.** the [rollb
9460: 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 ack journal] or
9470: 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 64 the [write-ahead
9480: 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 72 log]) for a par
9490: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 ticular database
94a0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 .** connection.
94b0: 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 See also [SQLIT
94c0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 E_FCNTL_FILE_POI
94d0: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 NTER]..**.** <li
94e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
94f0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a SYNC_OMITTED]].*
9500: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 * No longer in u
9510: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b se..**.** <li>[[
9520: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e SQLITE_FCNTL_SYN
9530: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 C]].** The [SQLI
9540: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f TE_FCNTL_SYNC] o
9550: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 pcode is generat
9560: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 ed internally by
9570: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 SQLite and.** s
9580: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 ent to the VFS i
9590: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 mmediately befor
95a0: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 e the xSync meth
95b0: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e od is invoked on
95c0: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 a.** database f
95d0: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 ile descriptor.
95e0: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 Or, if the xSync
95f0: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 method is not i
9600: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 nvoked .** becau
9610: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 se the user has
9620: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 configured SQLit
9630: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 e with .** [PRAG
9640: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c MA synchronous |
9650: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e PRAGMA synchron
9660: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 ous=OFF] it is i
9670: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 nvoked in place
9680: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 .** of the xSync
9690: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 method. In most
96a0: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e cases, the poin
96b0: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 ter argument pas
96c0: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 sed with.** this
96d0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 file-control is
96e0: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 NULL. However,
96f0: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 if the database
9700: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 file is being sy
9710: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 nced.** as part
9720: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 of a multi-datab
9730: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 ase commit, the
9740: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 argument points
9750: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 to a nul-termina
9760: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f ted.** string co
9770: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 ntaining the tra
9780: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 nsactions master
9790: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 -journal file na
97a0: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a me. VFSes that .
97b0: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 ** do not need t
97c0: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c his signal shoul
97d0: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 d silently ignor
97e0: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 e this opcode. A
97f0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 pplications .**
9800: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 should not call
9810: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
9820: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 ntrol()] with th
9830: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 is opcode as doi
9840: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 ng so may .** di
9850: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 srupt the operat
9860: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 ion of the speci
9870: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 alized VFSes tha
9880: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e t do require it.
9890: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 .**.** <li>[[S
98a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d QLITE_FCNTL_COMM
98b0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a IT_PHASETWO]].**
98c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
98d0: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 TL_COMMIT_PHASET
98e0: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 WO] opcode is ge
98f0: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c nerated internal
9900: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ly by SQLite.**
9910: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 and sent to the
9920: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e VFS after a tran
9930: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e saction has been
9940: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 committed immed
9950: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 iately.** but be
9960: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 fore the databas
9970: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 e is unlocked. V
9980: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 FSes that do not
9990: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 need this signa
99a0: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 l.** should sile
99b0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 ntly ignore this
99c0: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 opcode. Applica
99d0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 tions should not
99e0: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 call.** [sqlite
99f0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
9a00: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f ] with this opco
9a10: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d de as doing so m
9a20: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a ay disrupt the .
9a30: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 ** operation of
9a40: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 the specialized
9a50: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 VFSes that do re
9a60: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a quire it. .**.*
9a70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
9a80: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 CNTL_WIN32_AV_RE
9a90: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 TRY]].** ^The [S
9aa0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
9ab0: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 2_AV_RETRY] opco
9ac0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f de is used to co
9ad0: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 nfigure automati
9ae0: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 c.** retry count
9af0: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 s and intervals
9b00: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b for certain disk
9b10: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 I/O operations
9b20: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f for the.** windo
9b30: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 ws [VFS] in orde
9b40: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 r to provide rob
9b50: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 ustness in the p
9b60: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e resence of.** an
9b70: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d ti-virus program
9b80: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 s. By default,
9b90: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 the windows VFS
9ba0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 will retry file
9bb0: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 read,.** file wr
9bc0: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 ite, and file de
9bd0: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 lete operations
9be0: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 up to 10 times,
9bf0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 with a delay.**
9c00: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e of 25 millisecon
9c10: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 ds before the fi
9c20: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 rst retry and wi
9c30: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 th the delay inc
9c40: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e reasing.** by an
9c50: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d additional 25 m
9c60: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 illiseconds with
9c70: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 each subsequent
9c80: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a retry. This.**
9c90: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 opcode allows t
9ca0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 hese two values
9cb0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 (10 retries and
9cc0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 25 milliseconds
9cd0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 of delay).** to
9ce0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 be adjusted. Th
9cf0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 e values are cha
9d00: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 nged for all dat
9d10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
9d20: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 s.** within the
9d30: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 same process. T
9d40: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 he argument is a
9d50: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 pointer to an a
9d60: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 rray of two.** i
9d70: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 ntegers where th
9d80: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 e first integer
9d90: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 i the new retry
9da0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 count and the se
9db0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 cond.** integer
9dc0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 is the delay. I
9dd0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 f either integer
9de0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
9df0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a en the setting.*
9e00: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 * is not changed
9e10: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 but instead the
9e20: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 prior value of
9e30: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 that setting is
9e40: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 written.** into
9e50: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c the array entry,
9e60: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 allowing the cu
9e70: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 rrent retry sett
9e80: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e ings to be.** in
9e90: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 terrogated. The
9ea0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 zDbName paramet
9eb0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a er is ignored..*
9ec0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9ed0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f E_FCNTL_PERSIST_
9ee0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 WAL]].** ^The [S
9ef0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 QLITE_FCNTL_PERS
9f00: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 IST_WAL] opcode
9f10: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f is used to set o
9f20: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 r query the.** p
9f30: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c ersistent [WAL |
9f40: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 Write Ahead Log
9f50: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 ] setting. By d
9f60: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 efault, the auxi
9f70: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 liary.** write a
9f80: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 head log and sha
9f90: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 red memory files
9fa0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 used for transa
9fb0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a ction control.**
9fc0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c are automatical
9fd0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 ly deleted when
9fe0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 the latest conne
9ff0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 ction to the dat
a000: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e abase.** closes.
a010: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 Setting persis
a020: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 tent WAL mode ca
a030: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 uses those files
a040: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 to persist afte
a050: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 r.** close. Per
a060: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 sisting the file
a070: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e s is useful when
a080: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 other processes
a090: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 that do not.**
a0a0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 have write permi
a0b0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 ssion on the dir
a0c0: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e ectory containin
a0d0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 g the database f
a0e0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 ile want.** to r
a0f0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 ead the database
a100: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 file, as the WA
a110: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d L and shared mem
a120: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 ory files must e
a130: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 xist.** in order
a140: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 for the databas
a150: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 e to be readable
a160: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 . The fourth pa
a170: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 rameter to.** [s
a180: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
a190: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 rol()] for this
a1a0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 opcode should be
a1b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
a1c0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 integer..** Tha
a1d0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 t integer is 0 t
a1e0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 o disable persis
a1f0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 tent WAL mode or
a200: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 1 to enable per
a210: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d sistent.** WAL m
a220: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 ode. If the int
a230: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e eger is -1, then
a240: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 it is overwritt
a250: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 en with the curr
a260: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 ent.** WAL persi
a270: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a stence setting..
a280: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
a290: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 TE_FCNTL_POWERSA
a2a0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a FE_OVERWRITE]].*
a2b0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
a2c0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f CNTL_POWERSAFE_O
a2d0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 VERWRITE] opcode
a2e0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 is used to set
a2f0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 or query the.**
a300: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 persistent "powe
a310: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 rsafe-overwrite"
a320: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 or "PSOW" setti
a330: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 ng. The PSOW se
a340: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 tting.** determi
a350: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f nes the [SQLITE_
a360: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f IOCAP_POWERSAFE_
a370: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f OVERWRITE] bit o
a380: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 f the.** xDevice
a390: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 Characteristics
a3a0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 methods. The fou
a3b0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
a3c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
a3d0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 e_control()] for
a3e0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f this opcode sho
a3f0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 uld be a pointer
a400: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a to an integer..
a410: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 ** That integer
a420: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
a430: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 zero-damage mode
a440: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 or 1 to enable
a450: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d zero-damage.** m
a460: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 ode. If the int
a470: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e eger is -1, then
a480: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 it is overwritt
a490: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 en with the curr
a4a0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 ent.** zero-dama
a4b0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e ge mode setting.
a4c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
a4d0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 ITE_FCNTL_OVERWR
a4e0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 ITE]].** ^The [S
a4f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
a500: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 WRITE] opcode is
a510: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 invoked by SQLi
a520: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 te after opening
a530: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e .** a write tran
a540: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 saction to indic
a550: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 ate that, unless
a560: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 it is rolled ba
a570: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 ck for some.** r
a580: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 eason, the entir
a590: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
a5a0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 will be overwrit
a5b0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 ten by the curre
a5c0: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 nt .** transacti
a5d0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 on. This is used
a5e0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 by VACUUM opera
a5f0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 tions..**.** <li
a600: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
a610: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 VFSNAME]].** ^Th
a620: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
a630: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 VFSNAME] opcode
a640: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
a650: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 btain the names
a660: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 of.** all [VFSes
a670: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 ] in the VFS sta
a680: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 ck. The names a
a690: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 re of all VFS sh
a6a0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 ims and the.** f
a6b0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 inal bottom-leve
a6c0: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 l VFS are writte
a6d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 n into memory ob
a6e0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 tained from .**
a6f0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
a700: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c )] and the resul
a710: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 t is stored in t
a720: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c he char* variabl
a730: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f e.** that the fo
a740: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f urth parameter o
a750: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f f [sqlite3_file_
a760: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 control()] point
a770: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c s to..** The cal
a780: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ler is responsib
a790: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 le for freeing t
a7a0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 he memory when d
a7b0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a one. As with.**
a7c0: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f all file-contro
a7d0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 l actions, there
a7e0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 is no guarantee
a7f0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 that this will
a800: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 actually.** do a
a810: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 nything. Caller
a820: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c s should initial
a830: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 ize the char* va
a840: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c riable to a NULL
a850: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 .** pointer in c
a860: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f ase this file-co
a870: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 ntrol is not imp
a880: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 lemented. This
a890: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 file-control.**
a8a0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 is intended for
a8b0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f diagnostic use o
a8c0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b nly..**.** <li>[
a8d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 [SQLITE_FCNTL_VF
a8e0: 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e S_POINTER]].** ^
a8f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
a900: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f L_VFS_POINTER] o
a910: 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f pcode finds a po
a920: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 inter to the top
a930: 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 -level.** [VFSes
a940: 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 ] currently in u
a950: 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d se. ^(The argum
a960: 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 ent X in.** sqli
a970: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
a980: 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c (db,SQLITE_FCNTL
a990: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20 _VFS_POINTER,X)
a9a0: 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79 must be.** of ty
a9b0: 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73 pe "[sqlite3_vfs
a9c0: 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63 ] **". This opc
a9d0: 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58 odes will set *X
a9e0: 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72 .** to a pointer
a9f0: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 to the top-leve
aa00: 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 l VFS.)^.** ^Whe
aa10: 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74 n there are mult
aa20: 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69 iple VFS shims i
aa30: 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69 n the stack, thi
aa40: 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74 s opcode finds t
aa50: 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74 he.** upper-most
aa60: 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a shim only..**.*
aa70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
aa80: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a CNTL_PRAGMA]].**
aa90: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 ^Whenever a [PR
aaa0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 AGMA] statement
aab0: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 is parsed, an [S
aac0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
aad0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e MA] .** file con
aae0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 trol is sent to
aaf0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 the open [sqlite
ab00: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 3_file] object c
ab10: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 orresponding.**
ab20: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 to the database
ab30: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 file to which th
ab40: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 e pragma stateme
ab50: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 nt refers. ^The
ab60: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 argument.** to t
ab70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
ab80: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
ab90: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 ntrol is an arra
aba0: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 y of.** pointers
abb0: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 to strings (cha
abc0: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 r**) in which th
abd0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 e second element
abe0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a of the array.**
abf0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
ac00: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 the pragma and t
ac10: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 he third element
ac20: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 is the argument
ac30: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d to the.** pragm
ac40: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 a or NULL if the
ac50: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 pragma has no a
ac60: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 rgument. ^The h
ac70: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a andler for an.**
ac80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
ac90: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 RAGMA] file cont
aca0: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c rol can optional
acb0: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 ly make the firs
acc0: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 t element.** of
acd0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d the char** argum
ace0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 ent point to a s
acf0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 tring obtained f
ad00: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 rom [sqlite3_mpr
ad10: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 intf()].** or th
ad20: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 e equivalent and
ad30: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c that string wil
ad40: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 l become the res
ad50: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d ult of the pragm
ad60: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f a or.** the erro
ad70: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 r message if the
ad80: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e pragma fails. ^
ad90: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 If the.** [SQLIT
ada0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
adb0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 file control ret
adc0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 urns [SQLITE_NOT
add0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 FOUND], then nor
ade0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d mal .** [PRAGMA]
adf0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 processing cont
ae00: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 inues. ^If the
ae10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
ae20: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f AGMA].** file co
ae30: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 ntrol returns [S
ae40: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 QLITE_OK], then
ae50: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d the parser assum
ae60: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 es that the.** V
ae70: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 FS has handled t
ae80: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 he PRAGMA itself
ae90: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 and the parser
aea0: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f generates a no-o
aeb0: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 p.** prepared st
aec0: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c atement if resul
aed0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c t string is NULL
aee0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e , or that return
aef0: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 s a copy.** of t
af00: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 he result string
af10: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 if the string i
af20: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e s non-NULL..** ^
af30: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 If the [SQLITE_F
af40: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
af50: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e e control return
af60: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 s.** any result
af70: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 code other than
af80: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b [SQLITE_OK] or [
af90: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d SQLITE_NOTFOUND]
afa0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 , that means.**
afb0: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 that the VFS enc
afc0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f ountered an erro
afd0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 r while handling
afe0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e the [PRAGMA] an
aff0: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 d the.** compila
b000: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 tion of the PRAG
b010: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e MA fails with an
b020: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 error. ^The [S
b030: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
b040: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 MA].** file cont
b050: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 rol occurs at th
b060: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 e beginning of p
b070: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 ragma statement
b080: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a analysis and so.
b090: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f ** it is able to
b0a0: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d override built-
b0b0: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 in [PRAGMA] stat
b0c0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ements..**.** <l
b0d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
b0e0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a _BUSYHANDLER]].*
b0f0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
b100: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 CNTL_BUSYHANDLER
b110: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f ].** file-contro
b120: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 l may be invoked
b130: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 by SQLite on th
b140: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
b150: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c handle.** shortl
b160: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 y after it is op
b170: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f ened in order to
b180: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f provide a custo
b190: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 m VFS with acces
b1a0: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e s.** to the conn
b1b0: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e ections busy-han
b1c0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 dler callback. T
b1d0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f he argument is o
b1e0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 f type (void **)
b1f0: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f .** - an array o
b200: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 f two (void *) v
b210: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 alues. The first
b220: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c (void *) actual
b230: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 ly points.** to
b240: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 a function of ty
b250: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 pe (int (*)(void
b260: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 *)). In order t
b270: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e o invoke the con
b280: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 nections.** busy
b290: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 -handler, this f
b2a0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 unction should b
b2b0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 e invoked with t
b2c0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 he second (void
b2d0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 *) in.** the arr
b2e0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 ay as the only a
b2f0: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 rgument. If it r
b300: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
b310: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 then the operat
b320: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 ion.** should be
b330: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 retried. If it
b340: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 returns zero, th
b350: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f e custom VFS sho
b360: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a uld abandon the.
b370: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 ** current opera
b380: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e tion..**.** <li>
b390: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 [[SQLITE_FCNTL_T
b3a0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a EMPFILENAME]].**
b3b0: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 ^Application ca
b3c0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 n invoke the [SQ
b3d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 LITE_FCNTL_TEMPF
b3e0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f ILENAME] file-co
b3f0: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 ntrol.** to have
b400: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 SQLite generate
b410: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 a.** temporary
b420: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 filename using t
b430: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 he same algorith
b440: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 m that is follow
b450: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a ed to generate.*
b460: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 * temporary file
b470: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 names for TEMP t
b480: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 ables and other
b490: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 internal uses.
b4a0: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 The.** argument
b4b0: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 should be a char
b4c0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 ** which will be
b4d0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
b4e0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 filename.** wri
b4f0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 tten into memory
b500: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
b510: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
b520: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 ]. The caller s
b530: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 hould.** invoke
b540: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
b550: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 on the result t
b560: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 o avoid a memory
b570: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 leak..**.** <li
b580: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
b590: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 MMAP_SIZE]].** T
b5a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
b5b0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 _MMAP_SIZE] file
b5c0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 control is used
b5d0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 to query or set
b5e0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 the.** maximum
b5f0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
b600: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 that will be use
b610: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 d for memory-map
b620: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 ped I/O..** The
b630: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
b640: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 inter to a value
b650: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 of type sqlite3
b660: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 _int64 that.** i
b670: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 s an advisory ma
b680: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
b690: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c bytes in the fil
b6a0: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e e to memory map.
b6b0: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 The.** pointer
b6c0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 is overwritten
b6d0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c with the old val
b6e0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 ue. The limit i
b6f0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 s not changed if
b700: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 .** the value or
b710: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 iginally pointed
b720: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c to is negative,
b730: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 and so the curr
b740: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 ent limit .** ca
b750: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 n be queried by
b760: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 passing in a poi
b770: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 nter to a negati
b780: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 ve number. This
b790: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c .** file-control
b7a0: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 is used interna
b7b0: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 lly to implement
b7c0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 [PRAGMA mmap_si
b7d0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ze]..**.** <li>[
b7e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 [SQLITE_FCNTL_TR
b7f0: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 ACE]].** The [SQ
b800: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 LITE_FCNTL_TRACE
b810: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 ] file control p
b820: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 rovides advisory
b830: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
b840: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 to the VFS about
b850: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 what the higher
b860: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 layers of the S
b870: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 QLite stack are
b880: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 doing..** This f
b890: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 ile control is u
b8a0: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 sed by some VFS
b8b0: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 activity tracing
b8c0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 [shims]..** The
b8d0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a argument is a z
b8e0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
b8f0: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c tring. Higher l
b900: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 ayers in the.**
b910: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 SQLite stack may
b920: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e generate instan
b930: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 ces of this file
b940: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 control if.** t
b950: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 he [SQLITE_USE_F
b960: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 CNTL_TRACE] comp
b970: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
b980: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a is enabled..**.*
b990: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
b9a0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d CNTL_HAS_MOVED]]
b9b0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
b9c0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d FCNTL_HAS_MOVED]
b9d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e file control in
b9e0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 terprets its arg
b9f0: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f ument as a.** po
ba00: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
ba10: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 ger and it write
ba20: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f s a boolean into
ba30: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 that integer de
ba40: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 pending.** on wh
ba50: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
ba60: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 file has been r
ba70: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f enamed, moved, o
ba80: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 r deleted since
ba90: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 it.** was first
baa0: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c opened..**.** <l
bab0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
bac0: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c _WIN32_SET_HANDL
bad0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 E]].** The [SQLI
bae0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 TE_FCNTL_WIN32_S
baf0: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 ET_HANDLE] opcod
bb00: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 e is used for de
bb10: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a bugging. This.*
bb20: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 * opcode causes
bb30: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
bb40: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 method to swap
bb50: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 the file handle
bb60: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 with the one.**
bb70: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 pointed to by th
bb80: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e e pArg argument.
bb90: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 This capabilit
bba0: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 y is used during
bbb0: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 testing.** and
bbc0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 only needs to be
bbd0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 supported when
bbe0: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 SQLITE_TEST is d
bbf0: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c efined..**.** <l
bc00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
bc10: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 _WAL_BLOCK]].**
bc20: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
bc30: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 L_WAL_BLOCK] is
bc40: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 a signal to the
bc50: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69 VFS layer that i
bc60: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 t might.** be ad
bc70: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c vantageous to bl
bc80: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 ock on the next
bc90: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 WAL lock if the
bca0: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 lock is not imme
bcb0: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c diately.** avail
bcc0: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73 able. The WAL s
bcd0: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20 ubsystem issues
bce0: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69 this signal duri
bcf0: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 ng rare.** circu
bd00: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 mstances in orde
bd10: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c r to fix a probl
bd20: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79 em with priority
bd30: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 inversion..** A
bd40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
bd50: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 ld <em>not</em>
bd60: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f use this file-co
bd70: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ntrol..**.** <li
bd80: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
bd90: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 ZIPVFS]].** The
bda0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 [SQLITE_FCNTL_ZI
bdb0: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 PVFS] opcode is
bdc0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a implemented by z
bdd0: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 ipvfs only. All
bde0: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f other.** VFS sho
bdf0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 uld return SQLIT
be00: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 E_NOTFOUND for t
be10: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a his opcode..**.*
be20: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
be30: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 CNTL_RBU]].** Th
be40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
be50: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 RBU] opcode is i
be60: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68 mplemented by th
be70: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73 e special VFS us
be80: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 ed by.** the RBU
be90: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e extension only.
bea0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 All other VFS
beb0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 should return SQ
bec0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f LITE_NOTFOUND fo
bed0: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 r.** this opcode
bee0: 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a . .** </ul>.*/.
bef0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
bf00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 CNTL_LOCKSTATE
bf10: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 1.#
bf20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
bf30: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 NTL_GET_LOCKPROX
bf40: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 YFILE 2.#d
bf50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
bf60: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TL_SET_LOCKPROXY
bf70: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 FILE 3.#de
bf80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
bf90: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 L_LAST_ERRNO
bfa0: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
bfb0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
bfc0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 _SIZE_HINT
bfd0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 5.#defi
bfe0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
bff0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 CHUNK_SIZE
c000: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 6.#defin
c010: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 e SQLITE_FCNTL_F
c020: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 ILE_POINTER
c030: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 7.#define
c040: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 SQLITE_FCNTL_SY
c050: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 NC_OMITTED
c060: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 8.#define
c070: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
c080: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 32_AV_RETRY
c090: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 9.#define S
c0a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 QLITE_FCNTL_PERS
c0b0: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 IST_WAL
c0c0: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 10.#define SQ
c0d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 LITE_FCNTL_OVERW
c0e0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 RITE
c0f0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 11.#define SQL
c100: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d ITE_FCNTL_VFSNAM
c110: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
c120: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 12.#define SQLI
c130: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 TE_FCNTL_POWERSA
c140: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 FE_OVERWRITE
c150: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 13.#define SQLIT
c160: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 E_FCNTL_PRAGMA
c170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
c180: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
c190: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c _FCNTL_BUSYHANDL
c1a0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 ER 15
c1b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c1c0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 FCNTL_TEMPFILENA
c1d0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a ME 16.
c1e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
c1f0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 CNTL_MMAP_SIZE
c200: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 18.#
c210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
c220: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 NTL_TRACE
c230: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 19.#d
c240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
c250: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 TL_HAS_MOVED
c260: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 20.#de
c270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
c280: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 L_SYNC
c290: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 21.#def
c2a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
c2b0: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f _COMMIT_PHASETWO
c2c0: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 22.#defi
c2d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
c2e0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 WIN32_SET_HANDLE
c2f0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 23.#defin
c300: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 e SQLITE_FCNTL_W
c310: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 AL_BLOCK
c320: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 24.#define
c330: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 SQLITE_FCNTL_ZI
c340: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 PVFS
c350: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 25.#define
c360: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 SQLITE_FCNTL_RBU
c370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
c380: 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 26.#define S
c390: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f QLITE_FCNTL_VFS_
c3a0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 POINTER
c3b0: 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 27.#define SQ
c3c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e LITE_FCNTL_JOURN
c3d0: 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 AL_POINTER
c3e0: 20 20 32 38 0a 0a 2f 2a 20 64 65 70 72 65 63 61 28../* depreca
c3f0: 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 ted names */.#de
c400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f fine SQLITE_GET_
c410: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 LOCKPROXYFILE
c420: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f SQLITE_FCNTL_
c430: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c GET_LOCKPROXYFIL
c440: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 E.#define SQLITE
c450: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 _SET_LOCKPROXYFI
c460: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 LE SQLITE_F
c470: 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f CNTL_SET_LOCKPRO
c480: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 XYFILE.#define S
c490: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f QLITE_LAST_ERRNO
c4a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c SQL
c4b0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 ITE_FCNTL_LAST_E
c4c0: 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 RRNO.../*.** CAP
c4d0: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e I3REF: Mutex Han
c4e0: 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 dle.**.** The mu
c4f0: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 tex module withi
c500: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 n SQLite defines
c510: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d [sqlite3_mutex]
c520: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 to be an.** abs
c530: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 tract type for a
c540: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 mutex object.
c550: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
c560: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 never looks.** a
c570: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 t the internal r
c580: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 epresentation of
c590: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 an [sqlite3_mut
c5a0: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a ex]. It only.**
c5b0: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e deals with poin
c5c0: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c ters to the [sql
c5d0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 ite3_mutex] obje
c5e0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 ct..**.** Mutexe
c5f0: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 s are created us
c600: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
c610: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a ex_alloc()]..*/.
c620: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
c630: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c qlite3_mutex sql
c640: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a ite3_mutex;../*.
c650: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
c660: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 Interface Object
c670: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
c680: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ce of the sqlite
c690: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 3_vfs object def
c6a0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 ines the interfa
c6b0: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 ce between.** th
c6c0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e e SQLite core an
c6d0: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 d the underlying
c6e0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
c6f0: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a m. The "vfs".**
c700: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 in the name of
c710: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 the object stand
c720: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 s for "virtual f
c730: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 ile system". Se
c740: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 e.** the [VFS |
c750: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f VFS documentatio
c760: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 n] for further i
c770: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
c780: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 * The value of t
c790: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c he iVersion fiel
c7a0: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 d is initially 1
c7b0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 but may be larg
c7c0: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 er in.** future
c7d0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
c7e0: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 te. Additional
c7f0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 fields may be ap
c800: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a pended to this.*
c810: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 * object when th
c820: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 e iVersion value
c830: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 is increased.
c840: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74 Note that the st
c850: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 ructure.** of th
c860: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 e sqlite3_vfs ob
c870: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 ject changes in
c880: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 the transaction
c890: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 between.** SQLit
c8a0: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 e version 3.5.9
c8b0: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 and 3.6.0 and ye
c8c0: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 t the iVersion f
c8d0: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 ield was not.**
c8e0: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 modified..**.**
c8f0: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 The szOsFile fie
c900: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f ld is the size o
c910: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 f the subclassed
c920: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a [sqlite3_file].
c930: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 ** structure use
c940: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 d by this VFS.
c950: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 mxPathname is th
c960: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 e maximum length
c970: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d of.** a pathnam
c980: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a e in this VFS..*
c990: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 *.** Registered
c9a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 sqlite3_vfs obje
c9b0: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 cts are kept on
c9c0: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f a linked list fo
c9d0: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 rmed by.** the p
c9e0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 Next pointer. T
c9f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f he [sqlite3_vfs_
ca00: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 register()].** a
ca10: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f nd [sqlite3_vfs_
ca20: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e unregister()] in
ca30: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 terfaces manage
ca40: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 this list.** in
ca50: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 a thread-safe wa
ca60: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 y. The [sqlite3
ca70: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 _vfs_find()] int
ca80: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 erface.** search
ca90: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 es the list. Ne
caa0: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 ither the applic
cab0: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 ation code nor t
cac0: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d he VFS.** implem
cad0: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 entation should
cae0: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f use the pNext po
caf0: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 inter..**.** The
cb00: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 pNext field is
cb10: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 the only field i
cb20: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 n the sqlite3_vf
cb30: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 s.** structure t
cb40: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
cb50: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 ever modify. SQ
cb60: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 Lite will only a
cb70: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 ccess.** or modi
cb80: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 fy this field wh
cb90: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 ile holding a pa
cba0: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 rticular static
cbb0: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 mutex..** The ap
cbc0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
cbd0: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e never modify an
cbe0: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 ything within th
cbf0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a e sqlite3_vfs.**
cc00: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 object once the
cc10: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e object has been
cc20: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a registered..**.
cc30: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 ** The zName fie
cc40: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d ld holds the nam
cc50: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 e of the VFS mod
cc60: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d ule. The name m
cc70: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 ust.** be unique
cc80: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 across all VFS
cc90: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b modules..**.** [
cca0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
ccb0: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 en]].** ^SQLite
ccc0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 guarantees that
ccd0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 the zFilename pa
cce0: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e rameter to xOpen
ccf0: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 .** is either a
cd00: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 NULL pointer or
cd10: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a string obtained.
cd20: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 ** from xFullPat
cd30: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 hname() with an
cd40: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 optional suffix
cd50: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 added..** ^If a
cd60: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 suffix is added
cd70: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 to the zFilename
cd80: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 parameter, it w
cd90: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f ill.** consist o
cda0: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 f a single "-" c
cdb0: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 haracter followe
cdc0: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 d by no more tha
cdd0: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d n.** 11 alphanum
cde0: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 eric and/or "-"
cdf0: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e characters..** ^
ce00: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 SQLite further g
ce10: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a uarantees that.*
ce20: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c * the string wil
ce30: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 l be valid and u
ce40: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 nchanged until x
ce50: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 Close() is.** ca
ce60: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 lled. Because of
ce70: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 the previous se
ce80: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b ntence,.** the [
ce90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 sqlite3_file] ca
cea0: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 n safely store a
ceb0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a pointer to the.
cec0: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 ** filename if i
ced0: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d t needs to remem
cee0: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ber the filename
cef0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e for some reason
cf00: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c ..** If the zFil
cf10: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 ename parameter
cf20: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 to xOpen is a NU
cf30: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
cf40: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e xOpen.** must in
cf50: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d vent its own tem
cf60: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 porary name for
cf70: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e the file. ^When
cf80: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 ever the .** xFi
cf90: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
cfa0: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c is NULL it will
cfb0: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 also be the cas
cfc0: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c e that the.** fl
cfd0: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 ags parameter wi
cfe0: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 ll include [SQLI
cff0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
d000: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 CLOSE]..**.** Th
d010: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
d020: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c to xOpen() incl
d030: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 udes all bits se
d040: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 t in.** the flag
d050: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 s argument to [s
d060: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
d070: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 ]. Or if [sqlit
d080: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 e3_open()].** or
d090: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
d0a0: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 ()] is used, the
d0b0: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 n flags includes
d0c0: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 at least.** [SQ
d0d0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
d0e0: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
d0f0: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a PEN_CREATE]. .**
d100: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e If xOpen() open
d110: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e s a file read-on
d120: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 ly then it sets
d130: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a *pOutFlags to.**
d140: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 include [SQLITE
d150: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e _OPEN_READONLY].
d160: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 Other bits in
d170: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 *pOutFlags may b
d180: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 e set..**.** ^(S
d190: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 QLite will also
d1a0: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 add one of the f
d1b0: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 ollowing flags t
d1c0: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a o the xOpen().**
d1d0: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 call, depending
d1e0: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 on the object b
d1f0: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a eing opened:.**.
d200: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
d210: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
d220: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 IN_DB].** <li>
d230: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 [SQLITE_OPEN_MAI
d240: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c N_JOURNAL].** <l
d250: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
d260: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 _TEMP_DB].** <li
d270: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
d280: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a TEMP_JOURNAL].**
d290: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
d2a0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 PEN_TRANSIENT_DB
d2b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
d2c0: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e TE_OPEN_SUBJOURN
d2d0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
d2e0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 LITE_OPEN_MASTER
d2f0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 _JOURNAL].** <li
d300: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
d310: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a WAL].** </ul>)^.
d320: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 **.** The file I
d330: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f /O implementatio
d340: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 n can use the ob
d350: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 ject type flags
d360: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 to.** change the
d370: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 way it deals wi
d380: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 th files. For e
d390: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 xample, an appli
d3a0: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 cation.** that d
d3b0: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f oes not care abo
d3c0: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 ut crash recover
d3d0: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 y or rollback mi
d3e0: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 ght make.** the
d3f0: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 open of a journa
d400: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 l file a no-op.
d410: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 Writes to this
d420: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a journal would.**
d430: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c also be no-ops,
d440: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 and any attempt
d450: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 to read the jou
d460: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 rnal would retur
d470: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 n.** SQLITE_IOER
d480: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 R. Or the imple
d490: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 mentation might
d4a0: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 recognize that a
d4b0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c database.** fil
d4c0: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 e will be doing
d4d0: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 page-aligned sec
d4e0: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 tor reads and wr
d4f0: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d ites in a random
d500: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 .** order and se
d510: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 t up its I/O sub
d520: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 system according
d530: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ly..**.** SQLite
d540: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 might also add
d550: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
d560: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 wing flags to th
d570: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a e xOpen method:.
d580: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
d590: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f i> [SQLITE_OPEN_
d5a0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a DELETEONCLOSE].*
d5b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f * <li> [SQLITE_O
d5c0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a PEN_EXCLUSIVE].*
d5d0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ul>.**.** Th
d5e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 e [SQLITE_OPEN_D
d5f0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c ELETEONCLOSE] fl
d600: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c ag means the fil
d610: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 e should be.** d
d620: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 eleted when it i
d630: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 s closed. ^The
d640: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
d650: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 ETEONCLOSE].** w
d660: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 ill be set for T
d670: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e EMP databases an
d680: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 d their journals
d690: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 , transient.** d
d6a0: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 atabases, and su
d6b0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a bjournals..**.**
d6c0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 ^The [SQLITE_OP
d6d0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c EN_EXCLUSIVE] fl
d6e0: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 ag is always use
d6f0: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e d in conjunction
d700: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 .** with the [SQ
d710: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
d720: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 ] flag, which ar
d730: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a e both directly.
d740: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 ** analogous to
d750: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f the O_EXCL and O
d760: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 _CREAT flags of
d770: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 the POSIX open()
d780: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 .** API. The SQ
d790: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
d7a0: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 IVE flag, when p
d7b0: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a aired with the .
d7c0: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 ** SQLITE_OPEN_C
d7d0: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 REATE, is used t
d7e0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 o indicate that
d7f0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 file should alwa
d800: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 ys.** be created
d810: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 , and that it is
d820: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 an error if it
d830: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a already exists..
d840: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c ** It is <i>not<
d850: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 /i> used to indi
d860: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 cate the file sh
d870: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a ould be opened .
d880: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 ** for exclusive
d890: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e access..**.** ^
d8a0: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c At least szOsFil
d8b0: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 e bytes of memor
d8c0: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 y are allocated
d8d0: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 by SQLite.** to
d8e0: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 hold the [sqlit
d8f0: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 e3_file] structu
d900: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 re passed as the
d910: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 third.** argume
d920: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 nt to xOpen. Th
d930: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 e xOpen method d
d940: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a oes not have to.
d950: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 ** allocate the
d960: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 structure; it sh
d970: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 ould just fill i
d980: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 t in. Note that
d990: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 .** the xOpen me
d9a0: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 thod must set th
d9b0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
d9c0: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 Methods to eithe
d9d0: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 r.** a valid [sq
d9e0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
d9f0: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e ] object or to N
da00: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 ULL. xOpen must
da10: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e do.** this even
da20: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 if the open fai
da30: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 ls. SQLite expe
da40: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c cts that the sql
da50: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
da60: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 ds.** element wi
da70: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 ll be valid afte
da80: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 r xOpen returns
da90: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 regardless of th
daa0: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 e success.** or
dab0: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 failure of the x
dac0: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a Open call..**.**
dad0: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 [[sqlite3_vfs.x
dae0: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 Access]].** ^The
daf0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
db00: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 to xAccess() may
db10: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 be [SQLITE_ACCE
db20: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f SS_EXISTS].** to
db30: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 test for the ex
db40: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c istence of a fil
db50: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 e, or [SQLITE_AC
db60: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 CESS_READWRITE]
db70: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 to.** test wheth
db80: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 er a file is rea
db90: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 dable and writab
dba0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 le, or [SQLITE_A
dbb0: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 CCESS_READ].** t
dbc0: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 o test whether a
dbd0: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 file is at leas
dbe0: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 t readable. Th
dbf0: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a e file can be a.
dc00: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a ** directory..**
dc10: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
dc20: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 always allocate
dc30: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 at least mxPath
dc40: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 name+1 bytes for
dc50: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 the.** output b
dc60: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e uffer xFullPathn
dc70: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 ame. The exact
dc80: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 size of the outp
dc90: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 ut buffer.** is
dca0: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 also passed as a
dcb0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f parameter to bo
dcc0: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 th methods. If
dcd0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 the output buffe
dce0: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 r.** is not larg
dcf0: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 e enough, [SQLIT
dd00: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 E_CANTOPEN] shou
dd10: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 ld be returned.
dd20: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a Since this is.**
dd30: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 handled as a fa
dd40: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c tal error by SQL
dd50: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 ite, vfs impleme
dd60: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ntations should
dd70: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 endeavor.** to p
dd80: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 revent this by s
dd90: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d etting mxPathnam
dda0: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e e to a sufficien
ddb0: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e tly large value.
ddc0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 .**.** The xRand
ddd0: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 omness(), xSleep
dde0: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 (), xCurrentTime
ddf0: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 (), and xCurrent
de00: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 TimeInt64().** i
de10: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f nterfaces are no
de20: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 t strictly a par
de30: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 t of the filesys
de40: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 tem, but they ar
de50: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e e.** included in
de60: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 the VFS structu
de70: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e re for completen
de80: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e ess..** The xRan
de90: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 domness() functi
dea0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 on attempts to r
deb0: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 eturn nBytes byt
dec0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 es.** of good-qu
ded0: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 ality randomness
dee0: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 into zOut. The
def0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 return value is
df00: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e .** the actual n
df10: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f umber of bytes o
df20: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 f randomness obt
df30: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 ained..** The xS
df40: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 leep() method ca
df50: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 uses the calling
df60: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 thread to sleep
df70: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 for at.** least
df80: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d the number of m
df90: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 icroseconds give
dfa0: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e n. ^The xCurren
dfb0: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f tTime().** metho
dfc0: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 d returns a Juli
dfd0: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f an Day Number fo
dfe0: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 r the current da
dff0: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a te and time as.*
e000: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 * a floating poi
e010: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 nt value..** ^Th
e020: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e e xCurrentTimeIn
e030: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 t64() method ret
e040: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 urns, as an inte
e050: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a ger, the Julian.
e060: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 ** Day Number mu
e070: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 ltiplied by 8640
e080: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 0000 (the number
e090: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 of milliseconds
e0a0: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 in .** a 24-hou
e0b0: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 r day). .** ^SQ
e0c0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 Lite will use th
e0d0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e e xCurrentTimeIn
e0e0: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 t64() method to
e0f0: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a get the current.
e100: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 ** date and time
e110: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 if that method
e120: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 is available (if
e130: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f iVersion is 2 o
e140: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e r .** greater an
e150: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 d the function p
e160: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ointer is not NU
e170: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c LL) and will fal
e180: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 l back.** to xCu
e190: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 rrentTime() if x
e1a0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 CurrentTimeInt64
e1b0: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c () is unavailabl
e1c0: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 e..**.** ^The xS
e1d0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 etSystemCall(),
e1e0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 xGetSystemCall()
e1f0: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 , and xNestSyste
e200: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 mCall() interfac
e210: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 es.** are not us
e220: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 ed by the SQLite
e230: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 core. These op
e240: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 tional interface
e250: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a s are provided.*
e260: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 * by some VFSes
e270: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 to facilitate te
e280: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 sting of the VFS
e290: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 code. By overri
e2a0: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 ding .** system
e2b0: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 calls with funct
e2c0: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 ions under its c
e2d0: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 ontrol, a test p
e2e0: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 rogram can.** si
e2f0: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e mulate faults an
e300: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f d error conditio
e310: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 ns that would ot
e320: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69 herwise be diffi
e330: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 cult.** or impos
e340: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e sible to induce.
e350: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 The set of sys
e360: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 tem calls that c
e370: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e an be overridden
e380: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 .** varies from
e390: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 one VFS to anoth
e3a0: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 er, and from one
e3b0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 version of the
e3c0: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a same VFS to the.
e3d0: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 ** next. Applic
e3e0: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 ations that use
e3f0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
e400: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65 must be prepare
e410: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 d for any.** or
e420: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 all of these int
e430: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 erfaces to be NU
e440: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 LL or for their
e450: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e behavior to chan
e460: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 ge.** from one r
e470: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 elease to the ne
e480: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e xt. Application
e490: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d s must not attem
e4a0: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 pt to access.**
e4b0: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 any of these met
e4c0: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72 hods if the iVer
e4d0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 sion of the VFS
e4e0: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a is less than 3..
e4f0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
e500: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 t sqlite3_vfs sq
e510: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 lite3_vfs;.typed
e520: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 ef void (*sqlite
e530: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 3_syscall_ptr)(v
e540: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c oid);.struct sql
e550: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 ite3_vfs {. int
e560: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 iVersion;
e570: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 /* Structu
e580: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 re version numbe
e590: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 r (currently 3)
e5a0: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c */. int szOsFil
e5b0: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a e; /*
e5c0: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 Size of subclas
e5d0: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 sed sqlite3_file
e5e0: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 */. int mxPath
e5f0: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f name; /
e600: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 * Maximum file p
e610: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a athname length *
e620: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 /. sqlite3_vfs
e630: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 *pNext; /*
e640: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 Next registered
e650: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 VFS */. const c
e660: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 har *zName;
e670: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 /* Name of thi
e680: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 s virtual file s
e690: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 ystem */. void
e6a0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 *pAppData;
e6b0: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 /* Pointer t
e6c0: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 o application-sp
e6d0: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 ecific data */.
e6e0: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 int (*xOpen)(sq
e6f0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
e700: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 t char *zName, s
e710: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 qlite3_file*,.
e720: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 int
e730: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 flags, int *pOu
e740: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 tFlags);. int (
e750: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 *xDelete)(sqlite
e760: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
e770: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 ar *zName, int s
e780: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 yncDir);. int (
e790: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 *xAccess)(sqlite
e7a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
e7b0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 ar *zName, int f
e7c0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f lags, int *pResO
e7d0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 ut);. int (*xFu
e7e0: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 llPathname)(sqli
e7f0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
e800: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
e810: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 nOut, char *zOu
e820: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 t);. void *(*xD
e830: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 lOpen)(sqlite3_v
e840: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
e850: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 *zFilename);. v
e860: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 oid (*xDlError)(
e870: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
e880: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a t nByte, char *z
e890: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 ErrMsg);. void
e8a0: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 (*(*xDlSym)(sqli
e8b0: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 te3_vfs*,void*,
e8c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d const char *zSym
e8d0: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 bol))(void);. v
e8e0: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 oid (*xDlClose)(
e8f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f sqlite3_vfs*, vo
e900: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 id*);. int (*xR
e910: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 andomness)(sqlit
e920: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 e3_vfs*, int nBy
e930: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b te, char *zOut);
e940: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 . int (*xSleep)
e950: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
e960: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 nt microseconds)
e970: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 ;. int (*xCurre
e980: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f ntTime)(sqlite3_
e990: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a vfs*, double*);.
e9a0: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 int (*xGetLast
e9b0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 Error)(sqlite3_v
e9c0: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a fs*, int, char *
e9d0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 );. /*. ** The
e9e0: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 methods above a
e9f0: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 re in version 1
ea00: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 of the sqlite_vf
ea10: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 s object. ** de
ea20: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 finition. Those
ea30: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 that follow are
ea40: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f added in versio
ea50: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a n 2 or later. *
ea60: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 /. int (*xCurre
ea70: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c ntTimeInt64)(sql
ea80: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 ite3_vfs*, sqlit
ea90: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a e3_int64*);. /*
eaa0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 . ** The method
eab0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 s above are in v
eac0: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 ersions 1 and 2
ead0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 of the sqlite_vf
eae0: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 s object.. ** T
eaf0: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 hose below are f
eb00: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 or version 3 and
eb10: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 greater.. */.
eb20: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 int (*xSetSyste
eb30: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 mCall)(sqlite3_v
eb40: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
eb50: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f *zName, sqlite3_
eb60: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 syscall_ptr);.
eb70: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f sqlite3_syscall_
eb80: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d ptr (*xGetSystem
eb90: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 Call)(sqlite3_vf
eba0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
ebb0: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 zName);. const
ebc0: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 char *(*xNextSys
ebd0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 temCall)(sqlite3
ebe0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
ebf0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a r *zName);. /*.
ec00: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 ** The methods
ec10: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 above are in ve
ec20: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 rsions 1 through
ec30: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 3 of the sqlite
ec40: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a _vfs object.. *
ec50: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 * New fields may
ec60: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 be appended in
ec70: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e figure versions.
ec80: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 The iVersion.
ec90: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 ** value will i
eca0: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 ncrement wheneve
ecb0: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 r this happens.
ecc0: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 . */.};../*.**
ecd0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
ece0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 for the xAccess
ecf0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a VFS method.**.**
ed00: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
ed10: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 onstants can be
ed20: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 used as the thir
ed30: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a d parameter to.*
ed40: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 * the xAccess me
ed50: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 thod of an [sqli
ed60: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
ed70: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 They determine
ed80: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 .** what kind of
ed90: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 permissions the
eda0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
edb0: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a is looking for..
edc0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
edd0: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 CCESS_EXISTS, th
ede0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
edf0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b .** simply check
ee00: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
ee10: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 le exists..** Wi
ee20: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
ee30: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 _READWRITE, the
ee40: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
ee50: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 * checks whether
ee60: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 the named direc
ee70: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 tory is both rea
ee80: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 dable and writab
ee90: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 le.** (in other
eea0: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 words, if files
eeb0: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 can be added, re
eec0: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d moved, and renam
eed0: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 ed within.** the
eee0: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 directory)..**
eef0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 The SQLITE_ACCES
ef00: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 S_READWRITE cons
ef10: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c tant is currentl
ef20: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 y used only by t
ef30: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 he.** [temp_stor
ef40: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 e_directory prag
ef50: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 ma], though this
ef60: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e could change in
ef70: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c a future.** rel
ef80: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a ease of SQLite..
ef90: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
efa0: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 CCESS_READ, the
efb0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
efc0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 * checks whether
efd0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 the file is rea
efe0: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 dable. The SQLI
eff0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 TE_ACCESS_READ c
f000: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 onstant is.** cu
f010: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 rrently unused,
f020: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 though it might
f030: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 be used in a fut
f040: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a ure release of.*
f050: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 * SQLite..*/.#de
f060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
f070: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 SS_EXISTS 0.#
f080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
f090: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 CESS_READWRITE 1
f0a0: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 /* Used by PR
f0b0: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f AGMA temp_store_
f0c0: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 directory */.#de
f0d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
f0e0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 SS_READ 2
f0f0: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f /* Unused */../
f100: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
f110: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 lags for the xSh
f120: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 mLock VFS method
f130: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 .**.** These int
f140: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 eger constants d
f150: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 efine the variou
f160: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 s locking operat
f170: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 ions.** allowed
f180: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 by the xShmLock
f190: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 method of [sqlit
f1a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 e3_io_methods].
f1b0: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e The.** followin
f1c0: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c g are the only l
f1d0: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e egal combination
f1e0: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 s of flags to th
f1f0: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 e.** xShmLock me
f200: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e thod:.**.** <ul>
f210: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
f220: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 _SHM_LOCK | SQLI
f230: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a TE_SHM_SHARED.**
f240: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
f250: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f M_LOCK | SQLITE_
f260: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a SHM_EXCLUSIVE.**
f270: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
f280: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 M_UNLOCK | SQLIT
f290: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 E_SHM_SHARED.**
f2a0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d <li> SQLITE_SHM
f2b0: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 _UNLOCK | SQLITE
f2c0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a _SHM_EXCLUSIVE.*
f2d0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 * </ul>.**.** Wh
f2e0: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 en unlocking, th
f2f0: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 e same SHARED or
f300: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 EXCLUSIVE flag
f310: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 must be supplied
f320: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e as.** was given
f330: 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f on the correspo
f340: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a nding lock. .**
f350: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b .** The xShmLock
f360: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e method can tran
f370: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 sition between u
f380: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 nlocked and SHAR
f390: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e ED or.** between
f3a0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 unlocked and EX
f3b0: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e CLUSIVE. It can
f3c0: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 not transition b
f3d0: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a etween SHARED.**
f3e0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a and EXCLUSIVE..
f3f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
f400: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 E_SHM_UNLOCK
f410: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
f420: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 ITE_SHM_LOCK
f430: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
f440: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 QLITE_SHM_SHARED
f450: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 4.#define
f460: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c SQLITE_SHM_EXCL
f470: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a USIVE 8../*.*
f480: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 * CAPI3REF: Maxi
f490: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 mum xShmLock ind
f4a0: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 ex.**.** The xSh
f4b0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 mLock method on
f4c0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
f4d0: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c ods] may use val
f4e0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 ues.** between 0
f4f0: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 and this upper
f500: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 bound as its "of
f510: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a fset" argument..
f520: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f ** The SQLite co
f530: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 re will never at
f540: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 tempt to acquire
f550: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a or release a.**
f560: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 lock outside of
f570: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 this range.*/.#
f580: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
f590: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 M_NLOCK 8
f5a0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
f5b0: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 F: Initialize Th
f5c0: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 e SQLite Library
f5d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
f5e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
f5f0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c routine initial
f600: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 izes the.** SQLi
f610: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 te library. ^Th
f620: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
f630: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 wn() routine.**
f640: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 deallocates any
f650: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 resources that w
f660: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 ere allocated by
f670: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
f680: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 ize()..** These
f690: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 routines are des
f6a0: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 igned to aid in
f6b0: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 process initiali
f6c0: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 zation and.** sh
f6d0: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 utdown on embedd
f6e0: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 ed systems. Wor
f6f0: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 kstation applica
f700: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 tions using.** S
f710: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 QLite normally d
f720: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e o not need to in
f730: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 voke either of t
f740: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
f750: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
f760: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
f770: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 e() is an "effec
f780: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 tive" call if it
f790: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 is.** the first
f7a0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e time sqlite3_in
f7b0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e itialize() is in
f7c0: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 voked during the
f7d0: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 lifetime of.**
f7e0: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 the process, or
f7f0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 if it is the fir
f800: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f st time sqlite3_
f810: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
f820: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f invoked.** follo
f830: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 wing a call to s
f840: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
f850: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 ). ^(Only an ef
f860: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 fective call.**
f870: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 of sqlite3_initi
f880: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 alize() does any
f890: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e initialization.
f8a0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c All other call
f8b0: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 s.** are harmles
f8c0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a s no-ops.)^.**.*
f8d0: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 * A call to sqli
f8e0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 te3_shutdown() i
f8f0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 s an "effective"
f900: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 call if it is t
f910: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c he first.** call
f920: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
f930: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 down() since the
f940: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e last sqlite3_in
f950: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f itialize(). ^(O
f960: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 nly.** an effect
f970: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ive call to sqli
f980: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 te3_shutdown() d
f990: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 oes any deinitia
f9a0: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c lization..** All
f9b0: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c other valid cal
f9c0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ls to sqlite3_sh
f9d0: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 utdown() are har
f9e0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a mless no-ops.)^.
f9f0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
fa00: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
fa10: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 nterface is thre
fa20: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 adsafe, but sqli
fa30: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a te3_shutdown().*
fa40: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 * is not. The s
fa50: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
fa60: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 ) interface must
fa70: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 only be called
fa80: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 from a.** single
fa90: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 thread. All op
faa0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e en [database con
fab0: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 nections] must b
fac0: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c e closed and all
fad0: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 .** other SQLite
fae0: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 resources must
faf0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 be deallocated p
fb00: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 rior to invoking
fb10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 .** sqlite3_shut
fb20: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d down()..**.** Am
fb30: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 ong other things
fb40: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 , ^sqlite3_initi
fb50: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 alize() will inv
fb60: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f oke.** sqlite3_o
fb70: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c s_init(). Simil
fb80: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 arly, ^sqlite3_s
fb90: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c hutdown().** wil
fba0: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 l invoke sqlite3
fbb0: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a _os_end()..**.**
fbc0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
fbd0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
fbe0: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ne returns [SQLI
fbf0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
fc00: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f s..** ^If for so
fc10: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 me reason, sqlit
fc20: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
fc30: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 is unable to ini
fc40: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c tialize.** the l
fc50: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 ibrary (perhaps
fc60: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 it is unable to
fc70: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 allocate a neede
fc80: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a d resource such.
fc90: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 ** as a mutex) i
fca0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 t returns an [er
fcb0: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 ror code] other
fcc0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d than [SQLITE_OK]
fcd0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
fce0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
fcf0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c ) routine is cal
fd00: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 led internally b
fd10: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 y many other.**
fd20: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
fd30: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 s so that an app
fd40: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 lication usually
fd50: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
fd60: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 o.** invoke sqli
fd70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
fd80: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 directly. For
fd90: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 example, [sqlite
fda0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 3_open()].** cal
fdb0: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ls sqlite3_initi
fdc0: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 alize() so the S
fdd0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 QLite library wi
fde0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 ll be automatica
fdf0: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a lly.** initializ
fe00: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
fe10: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c _open()] is call
fe20: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 ed if it has not
fe30: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a be initialized.
fe40: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f ** already. ^Ho
fe50: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 wever, if SQLite
fe60: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
fe70: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d h the [SQLITE_OM
fe80: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 IT_AUTOINIT].**
fe90: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
fea0: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 ion, then the au
feb0: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f tomatic calls to
fec0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
fed0: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 ize().** are omi
fee0: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 tted and the app
fef0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 lication must ca
ff00: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ll sqlite3_initi
ff10: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 alize() directly
ff20: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 .** prior to usi
ff30: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c ng any other SQL
ff40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ite interface.
ff50: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 For maximum port
ff60: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 ability,.** it i
ff70: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 s recommended th
ff80: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 at applications
ff90: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 always invoke sq
ffa0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
ffb0: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 ().** directly p
ffc0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e rior to using an
ffd0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 y other SQLite i
ffe0: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 nterface. Futur
fff0: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 e releases.** of
10000 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 SQLite may requ
10010 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 ire this. In ot
10020 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 her words, the b
10030 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 ehavior exhibite
10040 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 d.** when SQLite
10050 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
10060 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 h [SQLITE_OMIT_A
10070 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 UTOINIT] might b
10080 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 ecome the.** def
10090 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e ault behavior in
100a0 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c some future rel
100b0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a ease of SQLite..
100c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
100d0 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 3_os_init() rout
100e0 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 ine does operati
100f0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 ng-system specif
10100 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 ic.** initializa
10110 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 tion of the SQLi
10120 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 te library. The
10130 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
10140 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 ).** routine und
10150 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f oes the effect o
10160 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 f sqlite3_os_ini
10170 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 t(). Typical ta
10180 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 sks.** performed
10190 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e by these routin
101a0 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 es include alloc
101b0 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 ation or dealloc
101c0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 ation.** of stat
101d0 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e ic resources, in
101e0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 itialization of
101f0 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 global variables
10200 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 ,.** setting up
10210 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 a default [sqlit
10220 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 e3_vfs] module,
10230 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a or setting up.**
10240 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 a default confi
10250 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b guration using [
10260 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
10270 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 ]..**.** The app
10280 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
10290 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 never invoke eit
102a0 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 her sqlite3_os_i
102b0 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 nit().** or sqli
102c0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 te3_os_end() dir
102d0 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c ectly. The appl
102e0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f ication should o
102f0 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 nly invoke.** sq
10300 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
10310 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 () and sqlite3_s
10320 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 hutdown(). The
10330 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
10340 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 ).** interface i
10350 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 s called automat
10360 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 ically by sqlite
10370 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 3_initialize() a
10380 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 nd.** sqlite3_os
10390 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 _end() is called
103a0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 by sqlite3_shut
103b0 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 down(). Appropr
103c0 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e iate.** implemen
103d0 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 tations for sqli
103e0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e te3_os_init() an
103f0 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 d sqlite3_os_end
10400 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 ().** are built
10410 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e into SQLite when
10420 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 it is compiled
10430 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 for Unix, Window
10440 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 s, or OS/2..** W
10450 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c hen [custom buil
10460 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f ds | built for o
10470 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a ther platforms].
10480 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 ** (using the [S
10490 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 QLITE_OS_OTHER=1
104a0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a ] compile-time.*
104b0 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 * option) the ap
104c0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 plication must s
104d0 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 upply a suitable
104e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
104f0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f for.** sqlite3_o
10500 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
10510 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 ite3_os_end().
10520 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 An application-s
10530 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 upplied.** imple
10540 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c mentation of sql
10550 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f ite3_os_init() o
10560 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 r sqlite3_os_end
10570 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 ().** must retur
10580 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e n [SQLITE_OK] on
10590 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d success and som
105a0 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 e other [error c
105b0 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 ode] upon.** fai
105c0 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f lure..*/.SQLITE_
105d0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
105e0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 69 TDCALL sqlite3_i
105f0 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b nitialize(void);
10600 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
10610 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
10620 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10630 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 void);.SQLITE_AP
10640 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
10650 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 73 5f CALL sqlite3_os_
10660 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 init(void);.SQLI
10670 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
10680 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
10690 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 3_os_end(void);.
106a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
106b0 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 Configuring The
106c0 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a SQLite Library.
106d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
106e0 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 3_config() inter
106f0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 face is used to
10700 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 make global conf
10710 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 iguration.** cha
10720 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 nges to SQLite i
10730 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 n order to tune
10740 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 SQLite to the sp
10750 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a ecific needs of.
10760 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
10770 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 on. The default
10780 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 configuration i
10790 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f s recommended fo
107a0 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 r most.** applic
107b0 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 ations and so th
107c0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 is routine is us
107d0 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 ually not necess
107e0 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 ary. It is.** p
107f0 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f rovided to suppo
10800 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 rt rare applicat
10810 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 ions with unusua
10820 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c l needs..**.** <
10830 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f b>The sqlite3_co
10840 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
10850 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 is not threadsa
10860 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 fe. The applicat
10870 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 ion.** must ensu
10880 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 re that no other
10890 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
108a0 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 es are invoked b
108b0 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 y other.** threa
108c0 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 ds while sqlite3
108d0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e _config() is run
108e0 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 ning.</b>.**.**
108f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 The sqlite3_conf
10900 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a ig() interface.*
10910 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e * may only be in
10920 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c voked prior to l
10930 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a ibrary initializ
10940 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b ation using.** [
10950 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
10960 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 ze()] or after s
10970 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 hutdown by [sqli
10980 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e te3_shutdown()].
10990 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f .** ^If sqlite3_
109a0 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c config() is call
109b0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 ed after [sqlite
109c0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 3_initialize()]
109d0 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 and before.** [s
109e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
109f0 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 )] then it will
10a00 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 return SQLITE_MI
10a10 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 SUSE..** Note, h
10a20 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 owever, that ^sq
10a30 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 lite3_config() c
10a40 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 an be called as
10a50 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 part of the.** i
10a60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
10a70 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
10a80 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 defined [sqlite3
10a90 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a _os_init()]..**.
10aa0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
10ab0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
10ac0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 _config() is an
10ad0 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 integer.** [conf
10ae0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
10af0 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 ] that determine
10b00 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 s.** what proper
10b10 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 ty of SQLite is
10b20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 to be configured
10b30 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 . Subsequent ar
10b40 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 guments.** vary
10b50 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
10b60 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 [configuration
10b70 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 option].** in th
10b80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
10b90 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 ..**.** ^When a
10ba0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
10bb0 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c tion is set, sql
10bc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 ite3_config() re
10bd0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
10be0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 ]..** ^If the op
10bf0 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 tion is unknown
10c00 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 or SQLite is una
10c10 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f ble to set the o
10c20 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 ption.** then th
10c30 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
10c40 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 ns a non-zero [e
10c50 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 rror code]..*/.S
10c60 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
10c70 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 LITE_CDECL sqlit
10c80 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e e3_config(int, .
10c90 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
10ca0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 3REF: Configure
10cb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
10cc0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ions.** METHOD:
10cd0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 sqlite3.**.** Th
10ce0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e e sqlite3_db_con
10cf0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
10d00 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 is used to make
10d10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a configuration.**
10d20 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 changes to a [d
10d30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
10d40 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 on]. The interf
10d50 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ace is similar t
10d60 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
10d70 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 nfig()] except t
10d80 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 hat the changes
10d90 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c apply to a singl
10da0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
10db0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 onnection] (spec
10dc0 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 ified in the fir
10dd0 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a st argument)..**
10de0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
10df0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
10e00 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 e3_db_config(D,V
10e10 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a ,...) is the.**
10e20 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 [SQLITE_DBCONFI
10e30 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f G_LOOKASIDE | co
10e40 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 nfiguration verb
10e50 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 ] - an integer c
10e60 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 ode .** that ind
10e70 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 icates what aspe
10e80 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 ct of the [datab
10e90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
10ea0 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 is being configu
10eb0 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 red..** Subseque
10ec0 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 nt arguments var
10ed0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 y depending on t
10ee0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e he configuration
10ef0 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 verb..**.** ^Ca
10f00 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 lls to sqlite3_d
10f10 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 b_config() retur
10f20 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 n SQLITE_OK if a
10f30 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 nd only if.** th
10f40 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 e call is consid
10f50 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e ered successful.
10f60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
10f70 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 nt SQLITE_CDECL
10f80 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
10f90 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 g(sqlite3*, int
10fa0 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a op, ...);../*.**
10fb0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
10fc0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 y Allocation Rou
10fd0 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 tines.**.** An i
10fe0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
10ff0 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
11000 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 he interface bet
11010 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 ween SQLite.** a
11020 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d nd low-level mem
11030 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
11040 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 outines..**.** T
11050 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 his object is us
11060 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 ed in only one p
11070 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 lace in the SQLi
11080 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a te interface..**
11090 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e A pointer to an
110a0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
110b0 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 s object is the
110c0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b argument to.** [
110d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
110e0 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 ] when the confi
110f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
11100 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f is.** [SQLITE_CO
11110 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 NFIG_MALLOC] or
11120 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
11130 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 ETMALLOC]. .**
11140 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 By creating an i
11150 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
11160 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 object.** and pa
11170 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c ssing it to [sql
11180 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 ite3_config]([SQ
11190 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
111a0 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 OC]).** during c
111b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e onfiguration, an
111c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e application can
111d0 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 specify an alte
111e0 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 rnative.** memor
111f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 y allocation sub
11200 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 system for SQLit
11210 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c e to use for all
11220 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d of its.** dynam
11230 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e ic memory needs.
11240 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
11250 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 SQLite comes wi
11260 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c th several [buil
11270 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f t-in memory allo
11280 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 cators].** that
11290 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 are perfectly ad
112a0 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f equate for the o
112b0 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f verwhelming majo
112c0 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 rity of applicat
112d0 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 ions.** and that
112e0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 this object is
112f0 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 only useful to a
11300 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f tiny minority o
11310 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a f applications.*
11320 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a * with specializ
11330 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ed memory alloca
11340 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 tion requirement
11350 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 s. This object
11360 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 is.** also used
11370 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f during testing o
11380 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 f SQLite in orde
11390 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 r to specify an
113a0 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d alternative.** m
113b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
113c0 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d that simulates m
113d0 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d emory out-of-mem
113e0 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 ory conditions i
113f0 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 n.** order to ve
11400 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 rify that SQLite
11410 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 recovers gracef
11420 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a ully from such.*
11430 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a * conditions..**
11440 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c .** The xMalloc,
11450 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 xRealloc, and x
11460 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 Free methods mus
11470 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a t work like the.
11480 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 ** malloc(), rea
11490 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 lloc() and free(
114a0 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d ) functions from
114b0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
114c0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c library..** ^SQL
114d0 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 ite guarantees t
114e0 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 hat the second a
114f0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 rgument to.** xR
11500 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 ealloc is always
11510 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 a value returne
11520 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c d by a prior cal
11530 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a l to xRoundup..*
11540 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c *.** xSize shoul
11550 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c d return the all
11560 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 ocated size of a
11570 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
11580 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 on.** previously
11590 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 obtained from x
115a0 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c Malloc or xReall
115b0 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 oc. The allocat
115c0 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c ed size.** is al
115d0 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 ways at least as
115e0 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 big as the requ
115f0 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d ested size but m
11600 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a ay be larger..**
11610 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 .** The xRoundup
11620 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
11630 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 what would be th
11640 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
11650 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 of.** a memory
11660 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e allocation given
11670 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 a particular re
11680 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d quested size. M
11690 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c ost memory.** al
116a0 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 locators round u
116b0 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 p memory allocat
116c0 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f ions at least to
116d0 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 the next multip
116e0 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d le.** of 8. Som
116f0 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 e allocators rou
11700 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 nd up to a large
11710 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f r multiple or to
11720 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a a power of 2..*
11730 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 * Every memory a
11740 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 llocation reques
11750 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f t coming in thro
11760 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c ugh [sqlite3_mal
11770 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 loc()].** or [sq
11780 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
11790 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f first calls xRo
117a0 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e undup. If xRoun
117b0 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a dup returns 0, .
117c0 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 ** that causes t
117d0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
117e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
117f0 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a on to fail..**.*
11800 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 * The xInit meth
11810 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 od initializes t
11820 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
11830 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c tor. For exampl
11840 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 e,.** it might a
11850 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 llocate any requ
11860 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 ire mutexes or i
11870 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e nitialize intern
11880 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 al data.** struc
11890 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 tures. The xShu
118a0 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 tdown method is
118b0 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 invoked (indirec
118c0 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 tly) by.** [sqli
118d0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 te3_shutdown()]
118e0 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c and should deall
118f0 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 ocate any resour
11900 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 ces acquired.**
11910 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 by xInit. The p
11920 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 AppData pointer
11930 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f is used as the o
11940 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f nly parameter to
11950 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 .** xInit and xS
11960 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 hutdown..**.** S
11970 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 QLite holds the
11980 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 [SQLITE_MUTEX_ST
11990 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 ATIC_MASTER] mut
119a0 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b ex when it invok
119b0 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 es.** the xInit
119c0 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 method, so the x
119d0 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 Init method need
119e0 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 not be threadsa
119f0 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 fe. The.** xShu
11a00 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 tdown method is
11a10 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d only called from
11a20 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
11a30 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 wn()] so it does
11a40 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 .** not need to
11a50 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 be threadsafe ei
11a60 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f ther. For all o
11a70 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 ther methods, SQ
11a80 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 Lite.** holds th
11a90 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f e [SQLITE_MUTEX_
11aa0 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 STATIC_MEM] mute
11ab0 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 x as long as the
11ac0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
11ad0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f IG_MEMSTATUS] co
11ae0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
11af0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 on is turned on
11b00 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 (which.** it is
11b10 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 by default) and
11b20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 so the methods a
11b30 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 re automatically
11b40 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 serialized..**
11b50 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c However, if [SQL
11b60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
11b70 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 ATUS] is disable
11b80 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 d, then the othe
11b90 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 r.** methods mus
11ba0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 t be threadsafe
11bb0 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 or else make the
11bc0 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 ir own arrangeme
11bd0 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 nts for.** seria
11be0 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 lization..**.**
11bf0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 SQLite will neve
11c00 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 r invoke xInit()
11c10 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 more than once
11c20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 without an inter
11c30 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 vening.** call t
11c40 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a o xShutdown()..*
11c50 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
11c60 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
11c70 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d hods sqlite3_mem
11c80 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 _methods;.struct
11c90 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
11ca0 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 hods {. void *(
11cb0 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 *xMalloc)(int);
11cc0 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 /* Memor
11cd0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e y allocation fun
11ce0 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 ction */. void
11cf0 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b (*xFree)(void*);
11d00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 /* Fre
11d10 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 e a prior alloca
11d20 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a tion */. void *
11d30 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 (*xRealloc)(void
11d40 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 *,int); /* Resi
11d50 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e ze an allocation
11d60 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a */. int (*xSiz
11d70 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 e)(void*);
11d80 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 /* Return t
11d90 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c he size of an al
11da0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e location */. in
11db0 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e t (*xRoundup)(in
11dc0 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 t); /*
11dd0 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 Round up request
11de0 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 size to allocat
11df0 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e ion size */. in
11e00 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a t (*xInit)(void*
11e10 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ); /*
11e20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d Initialize the m
11e30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
11e40 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 */. void (*xShu
11e50 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 tdown)(void*);
11e60 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c /* Deinitial
11e70 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 ize the memory a
11e80 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f llocator */. vo
11e90 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 id *pAppData;
11ea0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
11eb0 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 Argument to xIni
11ec0 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 t() and xShutdow
11ed0 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a n() */.};../*.**
11ee0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
11ef0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 guration Options
11f00 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 .** KEYWORDS: {c
11f10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
11f20 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ion}.**.** These
11f30 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 constants are t
11f40 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 he available int
11f50 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 eger configurati
11f60 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a on options that.
11f70 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 ** can be passed
11f80 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 as the first ar
11f90 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 gument to the [s
11fa0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
11fb0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
11fc0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 * New configurat
11fd0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 ion options may
11fe0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
11ff0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
12000 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 QLite..** Existi
12010 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ng configuration
12020 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 options might b
12030 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 e discontinued.
12040 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a Applications.**
12050 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 should check th
12060 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 e return code fr
12070 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 om [sqlite3_conf
12080 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 ig()] to make su
12090 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 re that.** the c
120a0 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 all worked. The
120b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
120c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
120d0 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e ll return a.** n
120e0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
120f0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e ode] if a discon
12100 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 tinued or unsupp
12110 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 orted configurat
12120 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 ion option.** is
12130 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
12140 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 <dl>.** [[SQLITE
12150 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
12160 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 READ]] <dt>SQLIT
12170 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
12180 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 HREAD</dt>.** <d
12190 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 d>There are no a
121a0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
121b0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 option. ^This
121c0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a option sets the.
121d0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ** [threading mo
121e0 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 de] to Single-th
121f0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 read. In other
12200 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c words, it disabl
12210 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 es.** all mutexi
12220 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 ng and puts SQLi
12230 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 te into a mode w
12240 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 here it can only
12250 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 be used.** by a
12260 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 single thread.
12270 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 ^If SQLite is
12280 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
12290 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
122a0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
122b0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
122c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
122d0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 on then.** it is
122e0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f not possible to
122f0 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 change the [thr
12300 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f eading mode] fro
12310 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a m its default.**
12320 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 value of Single
12330 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b -thread and so [
12340 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
12350 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a ] will return .*
12360 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d * [SQLITE_ERROR]
12370 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 if called with
12380 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 the SQLITE_CONFI
12390 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a G_SINGLETHREAD.*
123a0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
123b0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a option.</dd>.**.
123c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
123d0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d IG_MULTITHREAD]]
123e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
123f0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f IG_MULTITHREAD</
12400 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
12410 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
12420 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
12430 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 . ^This option
12440 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 sets the.** [thr
12450 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 eading mode] to
12460 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 Multi-thread. I
12470 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 n other words, i
12480 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 t disables.** mu
12490 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 texing on [datab
124a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
124b0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
124c0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
124d0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
124e0 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 tion is responsi
124f0 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a ble for serializ
12500 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a ing access to.**
12510 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
12520 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 ctions] and [pre
12530 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
12540 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 ]. But other mu
12550 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 texes.** are ena
12560 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c bled so that SQL
12570 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 ite will be safe
12580 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c to use in a mul
12590 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 ti-threaded.** e
125a0 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f nvironment as lo
125b0 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 ng as no two thr
125c0 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 eads attempt to
125d0 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 use the same.**
125e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
125f0 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d tion] at the sam
12600 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c e time. ^If SQL
12610 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
12620 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
12630 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
12640 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
12650 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
12660 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
12670 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 * it is not poss
12680 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 ible to set the
12690 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 Multi-thread [th
126a0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e reading mode] an
126b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f d.** [sqlite3_co
126c0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 nfig()] will ret
126d0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
126e0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 R] if called wit
126f0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f h the.** SQLITE_
12700 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
12710 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e AD configuration
12720 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a option.</dd>.**
12730 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
12740 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d FIG_SERIALIZED]]
12750 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
12760 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 IG_SERIALIZED</d
12770 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 t>.** <dd>There
12780 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 are no arguments
12790 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e to this option.
127a0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 ^This option s
127b0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 ets the.** [thre
127c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 ading mode] to S
127d0 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 erialized. In ot
127e0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 her words, this
127f0 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a option enables.*
12800 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e * all mutexes in
12810 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 cluding the recu
12820 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 rsive.** mutexes
12830 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
12840 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
12850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
12860 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 t] objects..** I
12870 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 n this mode (whi
12880 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c ch is the defaul
12890 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 t when SQLite is
128a0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
128b0 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 * [SQLITE_THREAD
128c0 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c SAFE=1]) the SQL
128d0 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c ite library will
128e0 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a itself serializ
128f0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b e access.** to [
12900 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
12910 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 ions] and [prepa
12920 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 red statements]
12930 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 so that the.** a
12940 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 pplication is fr
12950 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 ee to use the sa
12960 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e me [database con
12970 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a nection] or the.
12980 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 ** same [prepare
12990 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 d statement] in
129a0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
129b0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 s at the same ti
129c0 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 me..** ^If SQLit
129d0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
129e0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
129f0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
12a00 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
12a10 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
12a20 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
12a30 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 it is not possib
12a40 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 le to set the Se
12a50 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 rialized [thread
12a60 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a ing mode] and.**
12a70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
12a80 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ()] will return
12a90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
12aa0 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 f called with th
12ab0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 e.** SQLITE_CONF
12ac0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f IG_SERIALIZED co
12ad0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
12ae0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b on.</dd>.**.** [
12af0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
12b00 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 ALLOC]] <dt>SQLI
12b10 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
12b20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
12b30 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
12b40 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 G_MALLOC option
12b50 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
12b60 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
12b70 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 .** a pointer t
12b80 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
12b90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 the [sqlite3_me
12ba0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 m_methods] struc
12bb0 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 ture..** The arg
12bc0 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a ument specifies.
12bd0 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c ** alternative l
12be0 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 ow-level memory
12bf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
12c00 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 nes to be used i
12c10 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 n place of.** th
12c20 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
12c30 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 ion routines bui
12c40 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 lt into SQLite.)
12c50 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a ^ ^SQLite makes.
12c60 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 ** its own priva
12c70 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 te copy of the c
12c80 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 ontent of the [s
12c90 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
12ca0 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a ds] structure.**
12cb0 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c before the [sql
12cc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 ite3_config()] c
12cd0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 all returns.</dd
12ce0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
12cf0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
12d00 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 C]] <dt>SQLITE_C
12d10 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c ONFIG_GETMALLOC<
12d20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
12d30 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
12d40 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f _GETMALLOC optio
12d50 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
12d60 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a argument which.
12d70 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ** is a pointer
12d80 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
12d90 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
12da0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
12db0 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 cture..** The [s
12dc0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
12dd0 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 ds].** structure
12de0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
12df0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 the currently de
12e00 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c fined memory all
12e10 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
12e20 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 .)^.** This opti
12e30 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 on can be used t
12e40 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 o overload the d
12e50 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c efault memory al
12e60 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 location.** rout
12e70 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 ines with a wrap
12e80 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 per that simulat
12e90 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ions memory allo
12ea0 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f cation failure o
12eb0 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f r.** tracks memo
12ec0 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 ry usage, for ex
12ed0 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a ample. </dd>.**.
12ee0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
12ef0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c IG_MEMSTATUS]] <
12f00 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
12f10 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a _MEMSTATUS</dt>.
12f20 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c ** <dd> ^The SQL
12f30 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
12f40 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 ATUS option take
12f50 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e s single argumen
12f60 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a t of type int,.*
12f70 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 * interpreted as
12f80 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 a boolean, whic
12f90 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 h enables or dis
12fa0 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 ables the collec
12fb0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 tion of.** memor
12fc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 y allocation sta
12fd0 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 tistics. ^(When
12fe0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
12ff0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 n statistics are
13000 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 .** disabled, th
13010 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 e following SQLi
13020 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 te interfaces be
13030 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 come non-operati
13040 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a onal:.** <ul>.
13050 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
13060 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
13070 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
13080 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
13090 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c water()].** <l
130a0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 i> [sqlite3_soft
130b0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d _heap_limit64()]
130c0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 .** <li> [sqli
130d0 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a te3_status64()].
130e0 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 ** </ul>)^.**
130f0 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 ^Memory allocati
13100 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 on statistics ar
13110 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 e enabled by def
13120 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 ault unless SQLi
13130 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 te is.** compile
13140 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 d with [SQLITE_D
13150 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 EFAULT_MEMSTATUS
13160 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 ]=0 in which cas
13170 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f e memory.** allo
13180 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 cation statistic
13190 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 s are disabled b
131a0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f y default..** </
131b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
131c0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
131d0 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 H]] <dt>SQLITE_C
131e0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 ONFIG_SCRATCH</d
131f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 t>.** <dd> ^The
13200 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
13210 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 RATCH option spe
13220 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
13230 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a memory buffer.**
13240 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e that SQLite can
13250 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63 68 use for scratch
13260 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 memory. ^(Ther
13270 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
13280 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 ments.** to SQLI
13290 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
132a0 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e H: A pointer an
132b0 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 8-byte.** align
132c0 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ed memory buffer
132d0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 from which the
132e0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 scratch allocati
132f0 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 ons will be.** d
13300 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f rawn, the size o
13310 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 f each scratch a
13320 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a llocation (sz),.
13330 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d ** and the maxim
13340 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 um number of scr
13350 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 atch allocations
13360 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 (N).)^.** The f
13370 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 irst argument mu
13380 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 st be a pointer
13390 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 to an 8-byte ali
133a0 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f gned buffer.** o
133b0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 f at least sz*N
133c0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e bytes of memory.
133d0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
133e0 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68 not use more th
133f0 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 an one scratch b
13400 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 uffers per threa
13410 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 d..** ^SQLite wi
13420 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73 74 ll never request
13430 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 a scratch buffe
13440 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 r that is more t
13450 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 han 6.** times t
13460 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 he database page
13470 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 size..** ^If SQ
13480 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 Lite needs needs
13490 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 additional.** s
134a0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 cratch memory be
134b0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f yond what is pro
134c0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f vided by this co
134d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
134e0 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 on, then .** [sq
134f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
13500 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 will be used to
13510 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 obtain the memor
13520 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 y needed.<p>.**
13530 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63 ^When the applic
13540 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 ation provides a
13550 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 ny amount of scr
13560 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e atch memory usin
13570 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 g.** SQLITE_CONF
13580 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69 IG_SCRATCH, SQLi
13590 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 te avoids unnece
135a0 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b ssary large.** [
135b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 sqlite3_malloc|h
135c0 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d eap allocations]
135d0 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65 ..** This can he
135e0 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 lp [Robson proof
135f0 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 |prevent memory
13600 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 allocation failu
13610 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70 res] due to heap
13620 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f .** fragmentatio
13630 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 n in low-memory
13640 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 embedded systems
13650 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
13660 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
13670 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 _PAGECACHE]] <dt
13680 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
13690 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a AGECACHE</dt>.**
136a0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 <dd> ^The SQLIT
136b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
136c0 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 HE option specif
136d0 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f ies a memory poo
136e0 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 l.** that SQLite
136f0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 can use for the
13700 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 database page c
13710 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 ache with the de
13720 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 fault page.** ca
13730 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
13740 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f on. .** This co
13750 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
13760 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 on is a no-op if
13770 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
13780 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 define page.** c
13790 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
137a0 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 ion is loaded us
137b0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
137c0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e CONFIG_PCACHE2].
137d0 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 .** ^There are t
137e0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 hree arguments t
137f0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f o SQLITE_CONFIG_
13800 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 PAGECACHE: A poi
13810 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 nter to.** 8-byt
13820 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 e aligned memory
13830 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a (pMem), the siz
13840 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 63 e of each page c
13850 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a ache line (sz),.
13860 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 ** and the numbe
13870 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73 r of cache lines
13880 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 (N)..** The sz
13890 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
138a0 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 be the size of t
138b0 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 he largest datab
138c0 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 ase page.** (a p
138d0 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 ower of two betw
138e0 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 een 512 and 6553
138f0 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 6) plus some ext
13900 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 ra bytes for eac
13910 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 h.** page header
13920 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f . ^The number o
13930 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 f extra bytes ne
13940 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65 eded by the page
13950 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 header.** can b
13960 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 e determined usi
13970 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ng [SQLITE_CONFI
13980 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e G_PCACHE_HDRSZ].
13990 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c .** ^It is harml
139a0 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 ess, apart from
139b0 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 the wasted memor
139c0 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a y,.** for the sz
139d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 parameter to be
139e0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 larger than nec
139f0 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65 essary. The pMe
13a00 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 m.** argument mu
13a10 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e st be either a N
13a20 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 ULL pointer or a
13a30 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 pointer to an 8
13a40 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 -byte.** aligned
13a50 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 block of memory
13a60 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a of at least sz*
13a70 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69 N bytes, otherwi
13a80 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 se.** subsequent
13a90 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
13aa0 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e efined..** ^When
13ab0 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c pMem is not NUL
13ac0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 L, SQLite will s
13ad0 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68 65 trive to use the
13ae0 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 memory provided
13af0 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70 .** to satisfy p
13b00 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c age cache needs,
13b10 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f falling back to
13b20 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
13b30 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 ()] if.** a page
13b40 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c cache line is l
13b50 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79 arger than sz by
13b60 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 tes or if all of
13b70 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72 the pMem buffer
13b80 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65 64 .** is exhausted
13b90 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 ..** ^If pMem is
13ba0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e NULL and N is n
13bb0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 on-zero, then ea
13bc0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ch database conn
13bd0 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 ection.** does a
13be0 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 n initial bulk a
13bf0 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 llocation for pa
13c00 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a ge cache memory.
13c10 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
13c20 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 _malloc()] suffi
13c30 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 cient for N cach
13c40 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20 e lines if N is
13c50 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f positive or.** o
13c60 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20 f -1024*N bytes
13c70 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 if N is negative
13c80 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e , . ^If addition
13c90 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 al.** page cache
13ca0 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 memory is neede
13cb0 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 d beyond what is
13cc0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 provided by the
13cd0 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f initial.** allo
13ce0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c cation, then SQL
13cf0 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c ite goes to [sql
13d00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 ite3_malloc()] s
13d10 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61 eparately for ea
13d20 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c ch.** additional
13d30 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 cache line. </d
13d40 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
13d50 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 E_CONFIG_HEAP]]
13d60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
13d70 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c G_HEAP</dt>.** <
13d80 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f dd> ^The SQLITE_
13d90 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 CONFIG_HEAP opti
13da0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 on specifies a s
13db0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 tatic memory buf
13dc0 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c fer .** that SQL
13dd0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 ite will use for
13de0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 all of its dyna
13df0 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 mic memory alloc
13e00 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 ation needs.** b
13e10 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 eyond those prov
13e20 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c ided for by [SQL
13e30 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
13e40 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 CH] and.** [SQLI
13e50 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
13e60 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 CHE]..** ^The SQ
13e70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
13e80 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 option is only
13e90 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c available if SQL
13ea0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a ite is compiled.
13eb0 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b ** with either [
13ec0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 SQLITE_ENABLE_ME
13ed0 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 MSYS3] or [SQLIT
13ee0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 E_ENABLE_MEMSYS5
13ef0 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a ] and returns.**
13f00 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
13f10 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 if invoked other
13f20 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 wise..** ^There
13f30 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
13f40 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f nts to SQLITE_CO
13f50 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e NFIG_HEAP:.** An
13f60 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 8-byte aligned
13f70 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d pointer to the m
13f80 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 emory,.** the nu
13f90 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
13fa0 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 the memory buff
13fb0 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 er, and the mini
13fc0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 mum allocation s
13fd0 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ize..** ^If the
13fe0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 first pointer (t
13ff0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 he memory pointe
14000 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e r) is NULL, then
14010 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a SQLite reverts.
14020 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 ** to using its
14030 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 default memory a
14040 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 llocator (the sy
14050 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d stem malloc() im
14060 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a plementation),.*
14070 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 * undoing any pr
14080 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f ior invocation o
14090 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 f [SQLITE_CONFIG
140a0 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 _MALLOC]. ^If t
140b0 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 he.** memory poi
140c0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c nter is not NULL
140d0 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e then the altern
140e0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 ative memory.**
140f0 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 allocator is eng
14100 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 aged to handle a
14110 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 ll of SQLites me
14120 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
14130 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 needs..** The fi
14140 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 rst pointer (the
14150 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 memory pointer)
14160 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 must be aligned
14170 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a to an 8-byte.**
14180 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 boundary or sub
14190 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 sequent behavior
141a0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 of SQLite will
141b0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a be undefined..**
141c0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c The minimum all
141d0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 ocation size is
141e0 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e capped at 2**12.
141f0 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 Reasonable valu
14200 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 es.** for the mi
14210 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
14220 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 size are 2**5 t
14230 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 hrough 2**8.</dd
14240 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
14250 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 _CONFIG_MUTEX]]
14260 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
14270 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 G_MUTEX</dt>.**
14280 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 <dd> ^(The SQLIT
14290 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f E_CONFIG_MUTEX o
142a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
142b0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
142c0 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e ich is a.** poin
142d0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
142e0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
142f0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
14300 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 ] structure..**
14310 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 The argument spe
14320 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 cifies alternati
14330 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 ve low-level mut
14340 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 ex routines to b
14350 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 e used.** in pla
14360 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 ce the mutex rou
14370 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f tines built into
14380 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c SQLite.)^ ^SQL
14390 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ite makes a copy
143a0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 of.** the conte
143b0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 nt of the [sqlit
143c0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
143d0 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f ] structure befo
143e0 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a re the call to.*
143f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
14400 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 g()] returns. ^I
14410 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
14420 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
14430 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
14440 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
14450 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
14460 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
14470 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 hen.** the entir
14480 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 e mutexing subsy
14490 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 stem is omitted
144a0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 from the build a
144b0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 nd hence calls t
144c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
144d0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 nfig()] with the
144e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
144f0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 UTEX configurati
14500 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a on option will.*
14510 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
14520 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a _ERROR].</dd>.**
14530 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
14540 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c FIG_GETMUTEX]] <
14550 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
14560 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a _GETMUTEX</dt>.*
14570 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
14580 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
14590 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 TEX option takes
145a0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
145b0 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 nt which.** is a
145c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
145d0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
145e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
145f0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
14600 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 . The.** [sqlit
14610 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
14620 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 ].** structure i
14630 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 s filled with th
14640 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 e currently defi
14650 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e ned mutex routin
14660 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 es.)^.** This op
14670 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 tion can be used
14680 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 to overload the
14690 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 default mutex a
146a0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 llocation.** rou
146b0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 tines with a wra
146c0 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 pper used to tra
146d0 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 ck mutex usage f
146e0 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a or performance.*
146f0 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 * profiling or t
14700 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d esting, for exam
14710 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 ple. ^If SQLit
14720 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
14730 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
14740 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
14750 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
14760 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
14770 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
14780 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 the entire mutex
14790 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 ing subsystem is
147a0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 omitted from th
147b0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 e build and henc
147c0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 e calls to.** [s
147d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
147e0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
147f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
14800 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
14810 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 ption will.** re
14820 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 turn [SQLITE_ERR
14830 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 OR].</dd>.**.**
14840 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
14850 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e LOOKASIDE]] <dt>
14860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
14870 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 OKASIDE</dt>.**
14880 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 <dd> ^(The SQLIT
14890 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
148a0 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 DE option takes
148b0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 two arguments th
148c0 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 at determine.**
148d0 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 the default size
148e0 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 of lookaside me
148f0 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 mory on each [da
14900 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
14910 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 n]..** The first
14920 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
14930 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 .** size of each
14940 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 lookaside buffe
14950 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 r slot and the s
14960 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d econd is the num
14970 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 ber of.** slots
14980 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 allocated to eac
14990 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 h database conne
149a0 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 ction.)^ ^(SQLI
149b0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
149c0 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 IDE.** sets the
149d0 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c <i>default</i> l
149e0 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 ookaside size. T
149f0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e he [SQLITE_DBCON
14a00 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a FIG_LOOKASIDE].*
14a10 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c * option to [sql
14a20 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
14a30 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f ] can be used to
14a40 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b change the look
14a50 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 aside.** configu
14a60 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 ration on indivi
14a70 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 dual connections
14a80 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .)^ </dd>.**.**
14a90 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
14aa0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 PCACHE2]] <dt>SQ
14ab0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
14ac0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HE2</dt>.** <dd>
14ad0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f ^(The SQLITE_CO
14ae0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 NFIG_PCACHE2 opt
14af0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
14b00 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
14b10 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 h is .** a point
14b20 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 er to an [sqlite
14b30 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
14b40 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 2] object. This
14b50 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 object specifie
14b60 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 s.** the interfa
14b70 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 ce to a custom p
14b80 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d age cache implem
14b90 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e entation.)^.** ^
14ba0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 SQLite makes a c
14bb0 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 opy of the [sqli
14bc0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
14bd0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 ds2] object.</dd
14be0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
14bf0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 _CONFIG_GETPCACH
14c00 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f E2]] <dt>SQLITE_
14c10 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
14c20 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 2</dt>.** <dd> ^
14c30 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
14c40 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 IG_GETPCACHE2 op
14c50 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
14c60 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
14c70 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 ch.** is a point
14c80 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 er to an [sqlite
14c90 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
14ca0 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 2] object. SQLi
14cb0 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 te copies of.**
14cc0 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 the current page
14cd0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 cache implement
14ce0 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 ation into that
14cf0 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a object.)^ </dd>.
14d00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
14d10 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e ONFIG_LOG]] <dt>
14d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
14d30 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 G</dt>.** <dd> T
14d40 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
14d50 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 _LOG option is u
14d60 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 sed to configure
14d70 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 the SQLite.** g
14d80 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 lobal [error log
14d90 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 ]..** (^The SQLI
14da0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 TE_CONFIG_LOG op
14db0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 tion takes two a
14dc0 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e rguments: a poin
14dd0 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 ter to a.** func
14de0 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c tion with a call
14df0 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f signature of vo
14e00 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c id(*)(void*,int,
14e10 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a const char*), .*
14e20 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 * and a pointer
14e30 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 to void. ^If the
14e40 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 function pointe
14e50 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 r is not NULL, i
14e60 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 t is.** invoked
14e70 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 by [sqlite3_log(
14e80 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 )] to process ea
14e90 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 ch logging event
14ea0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 . ^If the.** fu
14eb0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 nction pointer i
14ec0 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c s NULL, the [sql
14ed0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 ite3_log()] inte
14ee0 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 rface becomes a
14ef0 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 no-op..** ^The v
14f00 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 oid pointer that
14f10 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 is the second a
14f20 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 rgument to SQLIT
14f30 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a E_CONFIG_LOG is.
14f40 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 ** passed throug
14f50 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 h as the first p
14f60 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
14f70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
14f80 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 ned logger.** fu
14f90 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 nction whenever
14fa0 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 that function is
14fb0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 invoked. ^The
14fc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
14fd0 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 to.** the logge
14fe0 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 r function is a
14ff0 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 copy of the firs
15000 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 t parameter to t
15010 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
15020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 .** [sqlite3_log
15030 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 ()] call and is
15040 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 intended to be a
15050 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f [result code] o
15060 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 r an.** [extende
15070 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 d result code].
15080 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 ^The third para
15090 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 meter passed to
150a0 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a the logger is.**
150b0 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 log message aft
150c0 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 er formatting vi
150d0 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 a [sqlite3_snpri
150e0 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 ntf()]..** The S
150f0 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e QLite logging in
15100 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 terface is not r
15110 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f eentrant; the lo
15120 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a gger function.**
15130 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 supplied by the
15140 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
15150 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 t not invoke any
15160 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
15170 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 e..** In a multi
15180 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 -threaded applic
15190 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 ation, the appli
151a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c cation-defined l
151b0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f ogger.** functio
151c0 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 n must be thread
151d0 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a safe. </dd>.**.*
151e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
151f0 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 G_URI]] <dt>SQLI
15200 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a TE_CONFIG_URI.**
15210 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 <dd>^(The SQLIT
15220 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 E_CONFIG_URI opt
15230 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
15240 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 le argument of t
15250 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e ype int..** If n
15260 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 on-zero, then UR
15270 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c I handling is gl
15280 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 obally enabled.
15290 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 If the parameter
152a0 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 is zero,.** the
152b0 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 n URI handling i
152c0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 s globally disab
152d0 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 led.)^ ^If URI h
152e0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 andling is globa
152f0 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 lly.** enabled,
15300 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 all filenames pa
15310 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 ssed to [sqlite3
15320 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
15330 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a e3_open_v2()],.*
15340 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 * [sqlite3_open1
15350 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 6()] or.** speci
15360 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 fied as part of
15370 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 [ATTACH] command
15380 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 s are interprete
15390 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 d as URIs, regar
153a0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 dless.** of whet
153b0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b her or not the [
153c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d SQLITE_OPEN_URI]
153d0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 flag is set whe
153e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a n the database.*
153f0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 * connection is
15400 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 opened. ^If it i
15410 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 s globally disab
15420 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 led, filenames a
15430 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 re.** only inter
15440 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 preted as URIs i
15450 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 f the SQLITE_OPE
15460 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 N_URI flag is se
15470 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 t when the.** da
15480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
15490 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 n is opened. ^(B
154a0 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 y default, URI h
154b0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 andling is globa
154c0 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e lly.** disabled.
154d0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c The default val
154e0 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 ue may be change
154f0 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 d by compiling w
15500 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
15510 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 TE_USE_URI] symb
15520 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a ol defined.)^.**
15530 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
15540 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 FIG_COVERING_IND
15550 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 EX_SCAN]] <dt>SQ
15560 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 LITE_CONFIG_COVE
15570 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a RING_INDEX_SCAN.
15580 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 ** <dd>^The SQLI
15590 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 TE_CONFIG_COVERI
155a0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 NG_INDEX_SCAN op
155b0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
155c0 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 gle integer.** a
155d0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
155e0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
155f0 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 a boolean in ord
15600 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 er to enable or
15610 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 disable.** the u
15620 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 se of covering i
15630 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 ndices for full
15640 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 table scans in t
15650 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a he query optimiz
15660 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 er..** ^The defa
15670 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 ult setting is d
15680 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 etermined.** by
15690 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f the [SQLITE_ALLO
156a0 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 W_COVERING_INDEX
156b0 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 _SCAN] compile-t
156c0 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 ime option, or i
156d0 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 s "on".** if tha
156e0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f t compile-time o
156f0 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 ption is omitted
15700 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 ..** The ability
15710 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 to disable the
15720 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 use of covering
15730 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c indices for full
15740 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 table scans.**
15750 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 is because some
15760 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 incorrectly code
15770 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 d legacy applica
15780 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 tions might malf
15790 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 unction.** when
157a0 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e the optimization
157b0 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 is enabled. Pr
157c0 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c oviding the abil
157d0 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c ity to.** disabl
157e0 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 e the optimizati
157f0 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c on allows the ol
15800 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 der, buggy appli
15810 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 cation code to w
15820 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 ork.** without c
15830 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 hange even with
15840 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f newer versions o
15850 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
15860 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
15870 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 PCACHE]] [[SQLIT
15880 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
15890 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 HE]].** <dt>SQLI
158a0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
158b0 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 and SQLITE_CONF
158c0 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 IG_GETPCACHE.**
158d0 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f <dd> These optio
158e0 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 ns are obsolete
158f0 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 and should not b
15900 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f e used by new co
15910 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 de..** They are
15920 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 retained for bac
15930 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
15940 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 lity but are now
15950 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 no-ops..** </dd
15960 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
15970 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d _CONFIG_SQLLOG]]
15980 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
15990 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 ONFIG_SQLLOG.**
159a0 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
159b0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c is only availabl
159c0 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 e if sqlite is c
159d0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
159e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
159f0 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 LE_SQLLOG] pre-p
15a00 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 rocessor macro d
15a10 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 efined. The firs
15a20 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c t argument shoul
15a30 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 d.** be a pointe
15a40 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 r to a function
15a50 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 of type void(*)(
15a60 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 void*,sqlite3*,c
15a70 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 onst char*, int)
15a80 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
15a90 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 should be of typ
15aa0 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 e (void*). The c
15ab0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
15ac0 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 ed by the librar
15ad0 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 y.** in three se
15ae0 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 parate circumsta
15af0 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 nces, identified
15b00 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 by the value pa
15b10 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 ssed as the.** f
15b20 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e ourth parameter.
15b30 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 If the fourth p
15b40 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 arameter is 0, t
15b50 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
15b60 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 connection.** p
15b70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 assed as the sec
15b80 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 ond argument has
15b90 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 just been opene
15ba0 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67 d. The third arg
15bb0 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 ument.** points
15bc0 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 to a buffer cont
15bd0 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 aining the name
15be0 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 of the main data
15bf0 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 base file. If th
15c00 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 e.** fourth para
15c10 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e meter is 1, then
15c20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
15c30 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72 nt that the thir
15c40 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 d parameter.** p
15c50 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 oints to has jus
15c60 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e t been executed.
15c70 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 Or, if the four
15c80 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
15c90 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 2, then.** the c
15ca0 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 onnection being
15cb0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 passed as the se
15cc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
15cd0 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 s being closed.
15ce0 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 The.** third par
15cf0 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64 ameter is passed
15d00 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 NULL In this ca
15d10 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 se. An example
15d20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a of using this.**
15d30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
15d40 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 ption can be see
15d50 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 n in the "test_s
15d60 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 qllog.c" source
15d70 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 file in.** the c
15d80 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 anonical SQLite
15d90 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 source tree.</dd
15da0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
15db0 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a _CONFIG_MMAP_SIZ
15dc0 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 E]].** <dt>SQLIT
15dd0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 E_CONFIG_MMAP_SI
15de0 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 ZE.** <dd>^SQLIT
15df0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 E_CONFIG_MMAP_SI
15e00 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d ZE takes two 64-
15e10 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c bit integer (sql
15e20 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 ite3_int64) valu
15e30 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 es.** that are t
15e40 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 he default mmap
15e50 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 size limit (the
15e60 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 default setting
15e70 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d for.** [PRAGMA m
15e80 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 map_size]) and t
15e90 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 he maximum allow
15ea0 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d ed mmap size lim
15eb0 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 it..** ^The defa
15ec0 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 ult setting can
15ed0 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 be overridden by
15ee0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 each database c
15ef0 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a onnection using.
15f00 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 ** either the [P
15f10 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d RAGMA mmap_size]
15f20 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 command, or by
15f30 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 using the.** [SQ
15f40 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f LITE_FCNTL_MMAP_
15f50 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 SIZE] file contr
15f60 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d ol. ^(The maxim
15f70 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 um allowed mmap
15f80 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 size.** will be
15f90 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 silently truncat
15fa0 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 ed if necessary
15fb0 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 so that it does
15fc0 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a not exceed the.*
15fd0 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d * compile-time m
15fe0 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 aximum mmap size
15ff0 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b set by the.** [
16000 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f SQLITE_MAX_MMAP_
16010 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 SIZE] compile-ti
16020 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 me option.)^.**
16030 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d ^If either argum
16040 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 ent to this opti
16050 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 on is negative,
16060 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 then that argume
16070 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 nt is.** changed
16080 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d to its compile-
16090 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a time default..**
160a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
160b0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 FIG_WIN32_HEAPSI
160c0 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 ZE]].** <dt>SQLI
160d0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f TE_CONFIG_WIN32_
160e0 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e HEAPSIZE.** <dd>
160f0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
16100 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a IG_WIN32_HEAPSIZ
16110 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 E option is only
16120 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 available if SQ
16130 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 Lite is.** compi
16140 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 led for Windows
16150 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 with the [SQLITE
16160 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 _WIN32_MALLOC] p
16170 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 re-processor mac
16180 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e ro.** defined. ^
16190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 SQLITE_CONFIG_WI
161a0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b N32_HEAPSIZE tak
161b0 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 es a 32-bit unsi
161c0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c gned integer val
161d0 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 ue.** that speci
161e0 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d fies the maximum
161f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 size of the cre
16200 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a ated heap..**.**
16210 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
16220 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a _PCACHE_HDRSZ]].
16230 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
16240 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 NFIG_PCACHE_HDRS
16250 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 Z.** <dd>^The SQ
16260 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
16270 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 HE_HDRSZ option
16280 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 takes a single p
16290 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a arameter which.*
162a0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 * is a pointer t
162b0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 o an integer and
162c0 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 writes into tha
162d0 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 t integer the nu
162e0 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a mber of extra.**
162f0 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20 bytes per page
16300 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 required for eac
16310 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 h page in [SQLIT
16320 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
16330 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 HE]..** The amou
16340 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 nt of extra spac
16350 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 e required can c
16360 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 hange depending
16370 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c on the compiler,
16380 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 .** target platf
16390 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 orm, and SQLite
163a0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b version..**.** [
163b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
163c0 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 MASZ]].** <dt>SQ
163d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 LITE_CONFIG_PMAS
163e0 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 Z.** <dd>^The SQ
163f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 LITE_CONFIG_PMAS
16400 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 Z option takes a
16410 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 single paramete
16420 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e r which.** is an
16430 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 unsigned intege
16440 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 r and sets the "
16450 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 Minimum PMA Size
16460 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 " for the multit
16470 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 hreaded.** sorte
16480 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 r to that intege
16490 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 r. The default
164a0 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 minimum PMA Size
164b0 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a is set by the.*
164c0 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 * [SQLITE_SORTER
164d0 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d _PMASZ] compile-
164e0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 time option. Ne
164f0 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 w threads are la
16500 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c unched.** to hel
16510 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 p with sort oper
16520 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 ations when mult
16530 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e ithreaded sortin
16540 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 g.** is enabled
16550 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 (using the [PRAG
16560 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d MA threads] comm
16570 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f and) and the amo
16580 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a unt of content.*
16590 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 * to be sorted e
165a0 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20 xceeds the page
165b0 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d size times the m
165c0 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a inimum of the.**
165d0 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 [PRAGMA cache_s
165e0 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 ize] setting and
165f0 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 20 this value..**
16600 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
16610 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
16620 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 INGLETHREAD 1
16630 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
16640 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16650 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 MULTITHREAD 2
16660 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
16670 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16680 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 _SERIALIZED 3
16690 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
166a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
166b0 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 G_MALLOC
166c0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 4 /* sqlite3_me
166d0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 m_methods* */.#d
166e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
166f0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 FIG_GETMALLOC
16700 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 5 /* sqlite3_
16710 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
16720 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16730 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 ONFIG_SCRATCH
16740 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 6 /* void*,
16750 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a int sz, int N *
16760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16770 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
16780 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 E 7 /* void
16790 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e *, int sz, int N
167a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
167b0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 TE_CONFIG_HEAP
167c0 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 8 /* vo
167d0 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 id*, int nByte,
167e0 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 int min */.#defi
167f0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16800 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 _MEMSTATUS 9
16810 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a /* boolean */.
16820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16830 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 ONFIG_MUTEX
16840 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 10 /* sqlite
16850 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 3_mutex_methods*
16860 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16870 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
16880 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 EX 11 /* sq
16890 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
168a0 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 ods* */./* previ
168b0 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e ously SQLITE_CON
168c0 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 FIG_CHUNKALLOC 1
168d0 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 2 which is now u
168e0 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 nused. */ .#defi
168f0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16900 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 _LOOKASIDE 13
16910 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a /* int int */.
16920 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16930 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 ONFIG_PCACHE
16940 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 14 /* no-op
16950 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16960 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
16970 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d HE 15 /* no-
16980 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 op */.#define SQ
16990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
169a0 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 16 /*
169b0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a xFunc, void* */.
169c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
169d0 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 ONFIG_URI
169e0 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 17 /* int */
169f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16a00 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 CONFIG_PCACHE2
16a10 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 18 /* sqlit
16a20 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
16a30 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 s2* */.#define S
16a40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
16a50 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a PCACHE2 19 /*
16a60 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
16a70 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 methods2* */.#de
16a80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16a90 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 IG_COVERING_INDE
16aa0 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e X_SCAN 20 /* in
16ab0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
16ac0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f ITE_CONFIG_SQLLO
16ad0 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 G 21 /* x
16ae0 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f Sqllog, void* */
16af0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16b00 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 CONFIG_MMAP_SIZE
16b10 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 22 /* sqlit
16b20 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 e3_int64, sqlite
16b30 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 3_int64 */.#defi
16b40 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16b50 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 _WIN32_HEAPSIZE
16b60 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 23 /* int
16b70 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 nByte */.#define
16b80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
16b90 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 CACHE_HDRSZ
16ba0 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 24 /* int *p
16bb0 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 sz */.#define SQ
16bc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 LITE_CONFIG_PMAS
16bd0 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 Z
16be0 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 25 /* unsigned
16bf0 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a int szPma */../*
16c00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 .** CAPI3REF: Da
16c10 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
16c20 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 n Configuration
16c30 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 Options.**.** Th
16c40 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
16c50 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 e the available
16c60 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 integer configur
16c70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 ation options th
16c80 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 at.** can be pas
16c90 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
16ca0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 d argument to th
16cb0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f e [sqlite3_db_co
16cc0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
16cd0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e e..**.** New con
16ce0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
16cf0 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ns may be added
16d00 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
16d10 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
16d20 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 Existing config
16d30 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
16d40 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 might be discont
16d50 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 inued. Applicat
16d60 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 ions.** should c
16d70 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
16d80 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 code from [sqlit
16d90 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
16da0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
16db0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f t.** the call wo
16dc0 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c rked. ^The [sql
16dd0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
16de0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c ] interface will
16df0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e return a.** non
16e00 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
16e10 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 e] if a disconti
16e20 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 nued or unsuppor
16e30 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ted configuratio
16e40 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 n option.** is i
16e50 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 nvoked..**.** <d
16e60 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 l>.** <dt>SQLITE
16e70 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
16e80 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e IDE</dt>.** <dd>
16e90 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 ^This option ta
16ea0 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 kes three additi
16eb0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 onal arguments t
16ec0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 hat determine th
16ed0 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 e .** [lookaside
16ee0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
16ef0 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e r] configuration
16f00 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 for the [databa
16f10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a se connection]..
16f20 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
16f30 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 gument (the thir
16f40 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b d parameter to [
16f50 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
16f60 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 g()] is a.** poi
16f70 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 nter to a memory
16f80 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 buffer to use f
16f90 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d or lookaside mem
16fa0 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ory..** ^The fir
16fb0 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 st argument afte
16fc0 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 r the SQLITE_DBC
16fd0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
16fe0 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e verb.** may be N
16ff0 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 ULL in which cas
17000 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c e SQLite will al
17010 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f locate the.** lo
17020 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 okaside buffer i
17030 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c tself using [sql
17040 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
17050 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
17060 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
17070 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
17080 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
17090 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 t. ^The third a
170a0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e rgument is the n
170b0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 umber of.** slot
170c0 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 s. The size of
170d0 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 the buffer in th
170e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
170f0 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 must be greater
17100 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 than.** or equa
17110 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 l to the product
17120 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 of the second a
17130 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e nd third argumen
17140 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a ts. The buffer.
17150 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e ** must be align
17160 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
17170 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 boundary. ^If t
17180 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
17190 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f nt to.** SQLITE_
171a0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
171b0 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 DE is not a mult
171c0 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 iple of 8, it is
171d0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 internally.** r
171e0 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 ounded down to t
171f0 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 he next smaller
17200 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 multiple of 8.
17210 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 ^(The lookaside
17220 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 memory.** config
17230 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 uration for a da
17240 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
17250 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 n can only be ch
17260 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a anged when that.
17270 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 ** connection is
17280 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 not currently u
17290 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d sing lookaside m
172a0 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 emory, or in oth
172b0 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e er words.** when
172c0 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 the "current va
172d0 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 lue" returned by
172e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f .** [sqlite3_db_
172f0 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 status](D,[SQLIT
17300 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
17310 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f DE],...) is zero
17320 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 ..** Any attempt
17330 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c to change the l
17340 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
17350 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 configuration wh
17360 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 en lookaside.**
17370 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 memory is in use
17380 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 leaves the conf
17390 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e iguration unchan
173a0 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ged and returns
173b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
173c0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ].)^</dd>.**.**
173d0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
173e0 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c FIG_ENABLE_FKEY<
173f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
17400 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 is option is use
17410 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 d to enable or d
17420 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 isable the enfor
17430 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f cement of.** [fo
17440 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 reign key constr
17450 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 aints]. There s
17460 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 hould be two add
17470 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
17480 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 s..** The first
17490 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 argument is an i
174a0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
174b0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 0 to disable FK
174c0 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 enforcement,.**
174d0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 positive to enab
174e0 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e le FK enforcemen
174f0 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f t or negative to
17500 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 leave FK enforc
17510 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 ement.** unchang
17520 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ed. The second
17530 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
17540 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
17550 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a eger into which.
17560 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ** is written 0
17570 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
17580 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f whether FK enfo
17590 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f rcement is off o
175a0 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e r on.** followin
175b0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 g this call. Th
175c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
175d0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c er may be a NULL
175e0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 pointer, in.**
175f0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 which case the F
17600 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 K enforcement se
17610 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 tting is not rep
17620 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 orted back. </dd
17630 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
17640 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
17650 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a LE_TRIGGER</dt>.
17660 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
17670 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
17680 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
17690 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 e [CREATE TRIGGE
176a0 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a R | triggers]..*
176b0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 * There should b
176c0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c e two additional
176d0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 arguments..** T
176e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
176f0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 t is an integer
17700 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 which is 0 to di
17710 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a sable triggers,.
17720 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 ** positive to e
17730 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f nable triggers o
17740 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 r negative to le
17750 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 ave the setting
17760 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 unchanged..** Th
17770 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
17780 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
17790 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e to an integer in
177a0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 to which.** is w
177b0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f ritten 0 or 1 to
177c0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 indicate whethe
177d0 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 r triggers are d
177e0 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c isabled or enabl
177f0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ed.** following
17800 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 this call. The
17810 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
17820 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 may be a NULL p
17830 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 ointer, in.** wh
17840 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 ich case the tri
17850 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 gger setting is
17860 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 not reported bac
17870 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c k. </dd>.**.** <
17880 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
17890 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
178a0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 LOOKASIDE
178b0 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 1001 /* void* i
178c0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e nt int */.#defin
178d0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
178e0 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 G_ENABLE_FKEY
178f0 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 1002 /* int i
17900 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nt* */.#define S
17910 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
17920 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 NABLE_TRIGGER 1
17930 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 003 /* int int*
17940 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 */.../*.** CAPI
17950 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 3REF: Enable Or
17960 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 Disable Extended
17970 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a Result Codes.**
17980 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
17990 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
179a0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 te3_extended_res
179b0 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 ult_codes() rout
179c0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 ine enables or d
179d0 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b isables the.** [
179e0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
179f0 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f codes] feature o
17a00 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 f SQLite. ^The e
17a10 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a xtended result.*
17a20 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 * codes are disa
17a30 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 bled by default
17a40 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 for historical c
17a50 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f ompatibility..*/
17a60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
17a70 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
17a80 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
17a90 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c result_codes(sql
17aa0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 ite3*, int onoff
17ab0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
17ac0 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 EF: Last Insert
17ad0 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a Rowid.** METHOD:
17ae0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
17af0 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f Each entry in mo
17b00 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 st SQLite tables
17b10 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 (except for [WI
17b20 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 THOUT ROWID] tab
17b30 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e les).** has a un
17b40 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e ique 64-bit sign
17b50 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 ed.** integer ke
17b60 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f y called the [RO
17b70 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 WID | "rowid"].
17b80 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c ^The rowid is al
17b90 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a ways available.*
17ba0 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 * as an undeclar
17bb0 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 ed column named
17bc0 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f ROWID, OID, or _
17bd0 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 ROWID_ as long a
17be0 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 s those.** names
17bf0 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 are not also us
17c00 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 ed by explicitly
17c10 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e declared column
17c20 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 s. ^If.** the ta
17c30 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e ble has a column
17c40 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 of type [INTEGE
17c50 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 R PRIMARY KEY] t
17c60 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a hen that column.
17c70 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c ** is another al
17c80 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 ias for the rowi
17c90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
17ca0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
17cb0 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 t_rowid(D) inter
17cc0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
17cd0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 [rowid] of the
17ce0 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 .** most recent
17cf0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 successful [INSE
17d00 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 RT] into a rowid
17d10 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 table or [virtu
17d20 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 al table].** on
17d30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
17d40 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 ion D..** ^Inser
17d50 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 ts into [WITHOUT
17d60 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 ROWID] tables a
17d70 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e re not recorded.
17d80 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 .** ^If no succe
17d90 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 ssful [INSERT]s
17da0 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 into rowid table
17db0 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f s.** have ever o
17dc0 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 ccurred on the d
17dd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
17de0 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 on D, .** then s
17df0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
17e00 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 rt_rowid(D) retu
17e10 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 rns zero..**.**
17e20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d ^(If an [INSERT]
17e30 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 occurs within a
17e40 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 trigger or with
17e50 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 in a [virtual ta
17e60 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 ble].** method,
17e70 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e then this routin
17e80 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 e will return th
17e90 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 e [rowid] of the
17ea0 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 inserted.** row
17eb0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 as long as the
17ec0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 trigger or virtu
17ed0 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 al table method
17ee0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 is running..** B
17ef0 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 ut once the trig
17f00 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 ger or virtual t
17f10 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 able method ends
17f20 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 , the value retu
17f30 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 rned .** by this
17f40 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 routine reverts
17f50 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 to what it was
17f60 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 before the trigg
17f70 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a er or virtual.**
17f80 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 table method be
17f90 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e gan.)^.**.** ^An
17fa0 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 [INSERT] that f
17fb0 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f ails due to a co
17fc0 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
17fd0 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 on is not a.** s
17fe0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
17ff0 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 T] and does not
18000 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
18010 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
18020 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e s.** routine. ^
18030 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 Thus INSERT OR F
18040 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 AIL, INSERT OR I
18050 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 GNORE, INSERT OR
18060 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e ROLLBACK,.** an
18070 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 d INSERT OR ABOR
18080 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 T make no change
18090 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 s to the return
180a0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a value of this.**
180b0 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 routine when th
180c0 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 eir insertion fa
180d0 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 ils. ^(When INS
180e0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a ERT OR REPLACE.*
180f0 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 * encounters a c
18100 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
18110 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 ion, it does not
18120 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 fail. The.** I
18130 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 NSERT continues
18140 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 to completion af
18150 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 ter deleting row
18160 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a s that caused.**
18170 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 the constraint
18180 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 problem so INSER
18190 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c T OR REPLACE wil
181a0 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a l always change.
181b0 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ** the return va
181c0 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 lue of this inte
181d0 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e rface.)^.**.** ^
181e0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 For the purposes
181f0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
18200 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 , an [INSERT] is
18210 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a considered to.*
18220 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 * be successful
18230 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 even if it is su
18240 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 bsequently rolle
18250 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 d back..**.** Th
18260 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 is function is a
18270 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c ccessible to SQL
18280 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 statements via
18290 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 the.** [last_ins
182a0 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 ert_rowid() SQL
182b0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
182c0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
182d0 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 hread performs a
182e0 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e new [INSERT] on
182f0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 the same.** dat
18300 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18310 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 while the [sqli
18320 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
18330 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 rowid()].** func
18340 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 tion is running
18350 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 and thus changes
18360 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 the last insert
18370 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 [rowid],.** the
18380 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 n the value retu
18390 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
183a0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
183b0 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 id()] is.** unpr
183c0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 edictable and mi
183d0 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 ght not equal ei
183e0 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 ther the old or
183f0 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 the new.** last
18400 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a insert [rowid]..
18410 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 */.SQLITE_API sq
18420 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 lite3_int64 SQLI
18430 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
18440 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
18450 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a owid(sqlite3*);.
18460 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
18470 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 Count The Numbe
18480 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
18490 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ed.** METHOD: sq
184a0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 lite3.**.** ^Thi
184b0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
184c0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
184d0 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 rows modified,
184e0 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 inserted or.** d
184f0 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f eleted by the mo
18500 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 st recently comp
18510 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 leted INSERT, UP
18520 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a DATE or DELETE.*
18530 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 * statement on t
18540 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
18550 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 ection specified
18560 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 by the only par
18570 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 ameter..** ^Exec
18580 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 uting any other
18590 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 type of SQL stat
185a0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d ement does not m
185b0 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a odify the value.
185c0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ** returned by t
185d0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a his function..**
185e0 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 .** ^Only change
185f0 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 s made directly
18600 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 by the INSERT, U
18610 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 PDATE or DELETE
18620 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a statement are.**
18630 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 considered - au
18640 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 xiliary changes
18650 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 caused by [CREAT
18660 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 E TRIGGER | trig
18670 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 gers], .** [fore
18680 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d ign key actions]
18690 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f or [REPLACE] co
186a0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 nstraint resolut
186b0 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e ion are not coun
186c0 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e ted..** .** Chan
186d0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 ges to a view th
186e0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 at are intercept
186f0 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 ed by .** [INSTE
18700 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 AD OF trigger |
18710 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 INSTEAD OF trigg
18720 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 ers] are not cou
18730 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 nted. ^The value
18740 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 .** returned by
18750 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
18760 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 () immediately a
18770 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 fter an INSERT,
18780 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 UPDATE or .** DE
18790 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 LETE statement r
187a0 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 un on a view is
187b0 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c always zero. Onl
187c0 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 y changes made t
187d0 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 o real .** table
187e0 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a s are counted..*
187f0 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 *.** Things are
18800 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 more complicated
18810 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f if the sqlite3_
18820 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 changes() functi
18830 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 on is.** execute
18840 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 d while a trigge
18850 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e r program is run
18860 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 ning. This may h
18870 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 appen if the.**
18880 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 program uses the
18890 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 [changes() SQL
188a0 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 function], or if
188b0 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c some other call
188c0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
188d0 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 invokes sqlite3
188e0 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 _changes() direc
188f0 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 tly. Essentially
18900 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a :.** .** <ul>.**
18910 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 <li> ^(Before
18920 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 entering a trig
18930 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 ger program the
18940 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
18950 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 y.** sqli
18960 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 te3_changes() fu
18970 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e nction is saved.
18980 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67 After the trigg
18990 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 er program .**
189a0 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 has finish
189b0 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c ed, the original
189c0 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 value is restor
189d0 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c ed.)^.** .** <
189e0 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 li> ^(Within a t
189f0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 rigger program e
18a00 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 ach INSERT, UPDA
18a10 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a TE and DELETE .*
18a20 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 * stateme
18a30 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 nt sets the valu
18a40 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 e returned by sq
18a50 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
18a60 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 .** upon
18a70 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f completion as no
18a80 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c rmal. Of course,
18a90 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c this value will
18aa0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a not include .**
18ab0 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e any chan
18ac0 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 ges performed by
18ad0 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 sub-triggers, a
18ae0 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 s the sqlite3_ch
18af0 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 anges() .**
18b00 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 value will be
18b10 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f saved and resto
18b20 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73 red after each s
18b30 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 ub-trigger has r
18b40 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a un.)^.** </ul>.*
18b50 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e * .** ^This mean
18b60 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68 s that if the ch
18b70 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 anges() SQL func
18b80 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 tion (or similar
18b90 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 ) is used.** by
18ba0 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 the first INSERT
18bb0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
18bc0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 TE statement wit
18bd0 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 hin a trigger, i
18be0 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 t .** returns th
18bf0 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 e value as set w
18c00 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 hen the calling
18c10 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 statement began
18c20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 executing..** ^I
18c30 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20 f it is used by
18c40 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 the second or su
18c50 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 bsequent such st
18c60 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 atement within a
18c70 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f trigger .** pro
18c80 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 gram, the value
18c90 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 returned reflect
18ca0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
18cb0 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 rows modified by
18cc0 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 the .** previou
18cd0 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 s INSERT, UPDATE
18ce0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 or DELETE state
18cf0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 ment within the
18d00 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a same trigger..**
18d10 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 .** See also the
18d20 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
18d30 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 changes()] inter
18d40 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f face, the.** [co
18d50 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 unt_changes prag
18d60 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 ma], and the [ch
18d70 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 anges() SQL func
18d80 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 tion]..**.** If
18d90 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
18da0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 d makes changes
18db0 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 on the same data
18dc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
18dd0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 ** while [sqlite
18de0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 3_changes()] is
18df0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 running then the
18e00 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a value returned.
18e10 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 ** is unpredicta
18e20 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
18e30 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 ingful..*/.SQLIT
18e40 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
18e50 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
18e60 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 _changes(sqlite3
18e70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
18e80 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 REF: Total Numbe
18e90 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
18ea0 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ed.** METHOD: sq
18eb0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 lite3.**.** ^Thi
18ec0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
18ed0 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d ns the total num
18ee0 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 ber of rows inse
18ef0 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f rted, modified o
18f00 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 r.** deleted by
18f10 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 all [INSERT], [U
18f20 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 PDATE] or [DELET
18f30 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f E] statements co
18f40 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 mpleted.** since
18f50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
18f60 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 nnection was ope
18f70 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 ned, including t
18f80 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73 hose executed as
18f90 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 .** part of trig
18fa0 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 ger programs. ^E
18fb0 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 xecuting any oth
18fc0 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 er type of SQL s
18fd0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 tatement.** does
18fe0 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 not affect the
18ff0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
19000 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f y sqlite3_total_
19010 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a changes()..** .*
19020 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 * ^Changes made
19030 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 as part of [fore
19040 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d ign key actions]
19050 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e are included in
19060 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 the.** count, b
19070 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 ut those made as
19080 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 part of REPLACE
19090 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f constraint reso
190a0 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f lution are.** no
190b0 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 t. ^Changes to a
190c0 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 view that are i
190d0 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e ntercepted by IN
190e0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 STEAD OF trigger
190f0 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f s .** are not co
19100 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 unted..** .** Se
19110 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 e also the [sqli
19120 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 te3_changes()] i
19130 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a nterface, the.**
19140 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 [count_changes
19150 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 pragma], and the
19160 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 [total_changes(
19170 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
19180 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
19190 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 rate thread make
191a0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
191b0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
191c0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 onnection.** whi
191d0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 le [sqlite3_tota
191e0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 l_changes()] is
191f0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 running then the
19200 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
19210 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 ed is unpredicta
19220 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
19230 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 ingful..*/.SQLIT
19240 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
19250 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
19260 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 _total_changes(s
19270 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
19280 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 CAPI3REF: Inter
19290 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e rupt A Long-Runn
192a0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 ing Query.** MET
192b0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
192c0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
192d0 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e n causes any pen
192e0 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 ding database op
192f0 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 eration to abort
19300 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 and.** return a
19310 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f t its earliest o
19320 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 pportunity. This
19330 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 routine is typi
19340 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 cally.** called
19350 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 in response to a
19360 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 user action suc
19370 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 h as pressing "C
19380 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 ancel".** or Ctr
19390 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 l-C where the us
193a0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 er wants a long
193b0 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 query operation
193c0 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 to halt.** immed
193d0 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 iately..**.** ^I
193e0 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c t is safe to cal
193f0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 l this routine f
19400 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 rom a thread dif
19410 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a ferent from the.
19420 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 ** thread that i
19430 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e s currently runn
19440 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 ing the database
19450 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 operation. But
19460 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 it.** is not sa
19470 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 fe to call this
19480 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b routine with a [
19490 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
194a0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 ion] that.** is
194b0 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 closed or might
194c0 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c close before sql
194d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
194e0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
194f0 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 ^If an SQL opera
19500 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 tion is very nea
19510 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 rly finished at
19520 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a the time when.**
19530 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
19540 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 pt() is called,
19550 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f then it might no
19560 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 t have an opport
19570 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 unity.** to be i
19580 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d nterrupted and m
19590 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f ight continue to
195a0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a completion..**.
195b0 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 ** ^An SQL opera
195c0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 tion that is int
195d0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 errupted will re
195e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 turn [SQLITE_INT
195f0 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 ERRUPT]..** ^If
19600 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 the interrupted
19610 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 SQL operation is
19620 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 an INSERT, UPDA
19630 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a TE, or DELETE.**
19640 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 that is inside
19650 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e an explicit tran
19660 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 saction, then th
19670 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 e entire transac
19680 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 tion.** will be
19690 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f rolled back auto
196a0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a matically..**.**
196b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
196c0 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 terrupt(D) call
196d0 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 is in effect unt
196e0 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 il all currently
196f0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 running.** SQL
19700 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 statements on [d
19710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19720 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 on] D complete.
19730 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 ^Any new SQL st
19740 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
19750 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
19760 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 er the sqlite3_i
19770 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 nterrupt() call
19780 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a and before the .
19790 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 ** running state
197a0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 ments reaches ze
197b0 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 ro are interrupt
197c0 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 ed as if they ha
197d0 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e d been.** runnin
197e0 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 g prior to the s
197f0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
19800 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 () call. ^New S
19810 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
19820 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 that are starte
19830 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e d after the runn
19840 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f ing statement co
19850 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f unt reaches zero
19860 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 are.** not effe
19870 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 cted by the sqli
19880 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e te3_interrupt().
19890 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 .** ^A call to s
198a0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
198b0 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 (D) that occurs
198c0 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e when there are n
198d0 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c o running.** SQL
198e0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 statements is a
198f0 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e no-op and has n
19900 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 o effect on SQL
19910 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
19920 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 at are started a
19930 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 fter the sqlite3
19940 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
19950 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a l returns..**.**
19960 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 If the database
19970 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 connection clos
19980 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 es while [sqlite
19990 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 3_interrupt()].*
199a0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 * is running the
199b0 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c n bad things wil
199c0 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e l likely happen.
199d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
199e0 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 oid SQLITE_STDCA
199f0 4c 4c 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 LL sqlite3_inter
19a00 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a rupt(sqlite3*);.
19a10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
19a20 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e Determine If An
19a30 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 SQL Statement I
19a40 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a s Complete.**.**
19a50 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
19a60 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e are useful durin
19a70 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 g command-line i
19a80 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e nput to determin
19a90 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 e if the.** curr
19aa0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 ently entered te
19ab0 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d xt seems to form
19ac0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 a complete SQL
19ad0 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 statement or.**
19ae0 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e if additional in
19af0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 put is needed be
19b00 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 fore sending the
19b10 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 text into.** SQ
19b20 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 Lite for parsing
19b30 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e . ^These routin
19b40 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 es return 1 if t
19b50 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a he input string.
19b60 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 ** appears to be
19b70 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 a complete SQL
19b80 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 statement. ^A s
19b90 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 tatement is judg
19ba0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 ed to be.** comp
19bb0 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 lete if it ends
19bc0 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e with a semicolon
19bd0 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f token and is no
19be0 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a t a prefix of a.
19bf0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 ** well-formed C
19c00 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 REATE TRIGGER st
19c10 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 atement. ^Semic
19c20 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 olons that are e
19c30 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a mbedded within.*
19c40 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c * string literal
19c50 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e s or quoted iden
19c60 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 tifier names or
19c70 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 comments are not
19c80 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 .** independent
19c90 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 tokens (they are
19ca0 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b part of the tok
19cb0 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 en in which they
19cc0 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 are.** embedded
19cd0 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f ) and thus do no
19ce0 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 t count as a sta
19cf0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f tement terminato
19d00 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a r. ^Whitespace.
19d10 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 ** and comments
19d20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 that follow the
19d30 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 final semicolon
19d40 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a are ignored..**.
19d50 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
19d60 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 es return 0 if t
19d70 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
19d80 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 incomplete. ^If
19d90 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c a.** memory all
19da0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 ocation fails, t
19db0 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d hen SQLITE_NOMEM
19dc0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
19dd0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
19de0 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 nes do not parse
19df0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
19e00 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c nts thus.** will
19e10 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 not detect synt
19e20 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 actically incorr
19e30 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e ect SQL..**.** ^
19e40 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e (If SQLite has n
19e50 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 ot been initiali
19e60 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 zed using [sqlit
19e70 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
19e80 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e prior .** to in
19e90 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 voking sqlite3_c
19ea0 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e omplete16() then
19eb0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
19ec0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
19ed0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
19ee0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d y by sqlite3_com
19ef0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 plete16(). If t
19f00 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 hat initializati
19f10 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 on fails,.** the
19f20 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c n the return val
19f30 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
19f40 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c complete16() wil
19f50 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a l be non-zero.**
19f60 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 regardless of w
19f70 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
19f80 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 e input SQL is c
19f90 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a omplete.)^.**.**
19fa0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 The input to [s
19fb0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
19fc0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 )] must be a zer
19fd0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
19fe0 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a UTF-8 string..**
19ff0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f .** The input to
1a000 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 [sqlite3_comple
1a010 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 te16()] must be
1a020 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
1a030 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 d.** UTF-16 stri
1a040 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 ng in native byt
1a050 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 e order..*/.SQLI
1a060 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
1a070 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
1a080 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 3_complete(const
1a090 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c char *sql);.SQL
1a0a0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
1a0b0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
1a0c0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f e3_complete16(co
1a0d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a nst void *sql);.
1a0e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1a0f0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c Register A Call
1a100 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 back To Handle S
1a110 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 QLITE_BUSY Error
1a120 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
1a130 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c busy-handler cal
1a140 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e lback} {busy han
1a150 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a dler}.** METHOD:
1a160 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
1a170 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 The sqlite3_busy
1a180 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 _handler(D,X,P)
1a190 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 routine sets a c
1a1a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1a1b0 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 X.** that might
1a1c0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
1a1d0 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e argument P when
1a1e0 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d ever.** an attem
1a1f0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 pt is made to ac
1a200 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20 cess a database
1a210 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 table associated
1a220 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 with.** [databa
1a230 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
1a240 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 when another th
1a250 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 read.** or proce
1a260 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 ss has the table
1a270 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 locked..** The
1a280 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
1a290 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 dler() interface
1a2a0 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c is used to impl
1a2b0 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 ement.** [sqlite
1a2c0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 3_busy_timeout()
1a2d0 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 ] and [PRAGMA bu
1a2e0 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a sy_timeout]..**.
1a2f0 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 ** ^If the busy
1a300 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
1a310 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 , then [SQLITE_B
1a320 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 USY].** is retur
1a330 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 ned immediately
1a340 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e upon encounterin
1a350 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 g the lock. ^If
1a360 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 the busy callba
1a370 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c ck.** is not NUL
1a380 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c L, then the call
1a390 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e back might be in
1a3a0 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 voked with two a
1a3b0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 rguments..**.**
1a3c0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
1a3d0 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 ent to the busy
1a3e0 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 handler is a cop
1a3f0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 y of the void* p
1a400 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 ointer which.**
1a410 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 is the third arg
1a420 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
1a430 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e _busy_handler().
1a440 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ^The second ar
1a450 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 gument to.** the
1a460 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 busy handler ca
1a470 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 llback is the nu
1a480 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 mber of times th
1a490 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 at the busy hand
1a4a0 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 ler has.** been
1a4b0 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 invoked previous
1a4c0 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ly for the same
1a4d0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 locking event.
1a4e0 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 ^If the.** busy
1a4f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
1a500 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 0, then no addi
1a510 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 tional attempts
1a520 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 are made to.** a
1a530 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 ccess the databa
1a540 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 se and [SQLITE_B
1a550 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 USY] is returned
1a560 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 .** to the appli
1a570 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 cation..** ^If t
1a580 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
1a590 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
1a5a0 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d en another attem
1a5b0 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f pt.** is made to
1a5c0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 access the data
1a5d0 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 base and the cyc
1a5e0 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a le repeats..**.*
1a5f0 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f * The presence o
1a600 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 f a busy handler
1a610 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e does not guaran
1a620 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c tee that it will
1a630 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 be invoked.** w
1a640 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 hen there is loc
1a650 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 k contention. ^I
1a660 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 f SQLite determi
1a670 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e nes that invokin
1a680 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 g the busy.** ha
1a690 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 ndler could resu
1a6a0 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b lt in a deadlock
1a6b0 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 , it will go ahe
1a6c0 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 ad and return [S
1a6d0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 QLITE_BUSY].** t
1a6e0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f o the applicatio
1a6f0 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 n instead of inv
1a700 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 oking the .** bu
1a710 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 sy handler..** C
1a720 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 onsider a scenar
1a730 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f io where one pro
1a740 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
1a750 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 a read lock that
1a760 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 .** it is trying
1a770 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
1a780 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 reserved lock a
1a790 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 nd.** a second p
1a7a0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
1a7b0 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 g a reserved loc
1a7c0 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 k that it is try
1a7d0 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 ing.** to promot
1a7e0 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 e to an exclusiv
1a7f0 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 e lock. The fir
1a800 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f st process canno
1a810 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 t proceed.** bec
1a820 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
1a830 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
1a840 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
1a850 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a process cannot.*
1a860 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 * proceed becaus
1a870 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 e it is blocked
1a880 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 by the first. I
1a890 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 f both processes
1a8a0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 .** invoke the b
1a8b0 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 usy handlers, ne
1a8c0 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 ither will make
1a8d0 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 any progress. T
1a8e0 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c herefore,.** SQL
1a8f0 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ite returns [SQL
1a900 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 ITE_BUSY] for th
1a910 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c e first process,
1a920 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 hoping that thi
1a930 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 s.** will induce
1a940 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
1a950 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 ss to release it
1a960 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 s read lock and
1a970 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 allow.** the sec
1a980 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 ond process to p
1a990 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 roceed..**.** ^T
1a9a0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 he default busy
1a9b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
1a9c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 ..**.** ^(There
1a9d0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 can only be a si
1a9e0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 ngle busy handle
1a9f0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 r defined for ea
1aa00 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ch.** [database
1aa10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 connection]. Se
1aa20 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 tting a new busy
1aa30 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 handler clears
1aa40 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c any.** previousl
1aa50 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e y set handler.)^
1aa60 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c ^Note that cal
1aa70 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 ling [sqlite3_bu
1aa80 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a sy_timeout()].**
1aa90 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b or evaluating [
1aaa0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 PRAGMA busy_time
1aab0 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e out=N] will chan
1aac0 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 ge the.** busy h
1aad0 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 andler and thus
1aae0 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f clear any previo
1aaf0 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 usly set busy ha
1ab00 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ndler..**.** The
1ab10 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 busy callback s
1ab20 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 hould not take a
1ab30 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 ny actions which
1ab40 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 modify the.** d
1ab50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1ab60 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
1ab70 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
1ab80 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 . In other word
1ab90 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 s,.** the busy h
1aba0 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 andler is not re
1abb0 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 entrant. Any su
1abc0 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 ch actions.** re
1abd0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 sult in undefine
1abe0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a d behavior..** .
1abf0 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 ** A busy handle
1ac00 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 r must not close
1ac10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
1ac20 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b nnection.** or [
1ac30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1ac40 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 nt] that invoked
1ac50 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
1ac60 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 r..*/.SQLITE_API
1ac70 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
1ac80 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79 ALL sqlite3_busy
1ac90 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
1aca0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c *, int(*)(void*,
1acb0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f int), void*);../
1acc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
1acd0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 et A Busy Timeou
1ace0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
1acf0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ite3.**.** ^This
1ad00 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 routine sets a
1ad10 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 [sqlite3_busy_ha
1ad20 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e ndler | busy han
1ad30 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 dler] that sleep
1ad40 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 s.** for a speci
1ad50 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 fied amount of t
1ad60 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 ime when a table
1ad70 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 is locked. ^Th
1ad80 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c e handler.** wil
1ad90 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 l sleep multiple
1ada0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 times until at
1adb0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 least "ms" milli
1adc0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
1add0 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 ing.** have accu
1ade0 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 mulated. ^After
1adf0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d at least "ms" m
1ae00 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 illiseconds of s
1ae10 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 leeping,.** the
1ae20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 handler returns
1ae30 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 0 which causes [
1ae40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1ae50 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 to return.** [SQ
1ae60 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a LITE_BUSY]..**.*
1ae70 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 * ^Calling this
1ae80 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 routine with an
1ae90 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 argument less th
1aea0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a an or equal to z
1aeb0 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 ero.** turns off
1aec0 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 all busy handle
1aed0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 rs..**.** ^(Ther
1aee0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
1aef0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
1af00 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 ler for a partic
1af10 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ular.** [databas
1af20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 e connection] at
1af30 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e any given momen
1af40 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 t. If another b
1af50 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 usy handler.** w
1af60 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 as defined (usi
1af70 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ng [sqlite3_busy
1af80 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 _handler()]) pri
1af90 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a or to calling.**
1afa0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 this routine, t
1afb0 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 hat other busy h
1afc0 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 andler is cleare
1afd0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 d.)^.**.** See a
1afe0 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 lso: [PRAGMA bu
1aff0 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 sy_timeout].*/.S
1b000 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
1b010 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1b020 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
1b030 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 t(sqlite3*, int
1b040 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ms);../*.** CAPI
1b050 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 3REF: Convenienc
1b060 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 e Routines For R
1b070 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a unning Queries.*
1b080 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
1b090 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 3.**.** This is
1b0a0 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 a legacy interfa
1b0b0 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 ce that is prese
1b0c0 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rved for backwar
1b0d0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
1b0e0 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 ..** Use of this
1b0f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f interface is no
1b100 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a t recommended..*
1b110 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a *.** Definition:
1b120 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 A <b>result tab
1b130 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 le</b> is memory
1b140 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 data structure
1b150 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a created by the.*
1b160 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 * [sqlite3_get_t
1b170 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 able()] interfac
1b180 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 e. A result tab
1b190 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a le records the.*
1b1a0 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 * complete query
1b1b0 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e results from on
1b1c0 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 e or more querie
1b1d0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 s..**.** The tab
1b1e0 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 le conceptually
1b1f0 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 has a number of
1b200 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 rows and columns
1b210 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 . But.** these
1b220 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 numbers are not
1b230 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 part of the resu
1b240 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e lt table itself.
1b250 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 These.** numbe
1b260 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 rs are obtained
1b270 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 separately. Let
1b280 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 N be the number
1b290 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 of rows.** and
1b2a0 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 M be the number
1b2b0 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a of columns..**.*
1b2c0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
1b2d0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
1b2e0 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f pointers to zero
1b2f0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
1b300 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 8 strings..** Th
1b310 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 ere are (N+1)*M
1b320 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 elements in the
1b330 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 array. The firs
1b340 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 t M pointers poi
1b350 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 nt.** to zero-te
1b360 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 rminated strings
1b370 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 that contain t
1b380 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 he names of the
1b390 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 columns..** The
1b3a0 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 remaining entrie
1b3b0 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 s all point to q
1b3c0 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e uery results. N
1b3d0 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c ULL values resul
1b3e0 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 t.** in NULL poi
1b3f0 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 nters. All othe
1b400 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 r values are in
1b410 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f their UTF-8 zero
1b420 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 -terminated.** s
1b430 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 tring representa
1b440 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 tion as returned
1b450 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c by [sqlite3_col
1b460 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a umn_text()]..**.
1b470 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
1b480 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 e might consist
1b490 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d of one or more m
1b4a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1b4b0 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 s..** It is not
1b4c0 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 safe to pass a r
1b4d0 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 esult table dire
1b4e0 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 ctly to [sqlite3
1b4f0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 _free()]..** A r
1b500 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 esult table shou
1b510 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 ld be deallocate
1b520 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
1b530 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a _free_table()]..
1b540 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 **.** ^(As an ex
1b550 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 ample of the res
1b560 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 ult table format
1b570 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 , suppose a quer
1b580 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 y result.** is a
1b590 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
1b5a0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1b5b0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d e>.** Nam
1b5c0 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a e | Age.*
1b5d0 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d * -------
1b5e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1b5f0 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 .** Alice
1b600 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 | 43.**
1b610 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 Bob
1b620 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 | 28.**
1b630 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 Cindy | 2
1b640 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 1.** </pre></blo
1b650 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
1b660 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c here are two col
1b670 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 umn (M==2) and t
1b680 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 hree rows (N==3)
1b690 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 . Thus the.** r
1b6a0 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 esult table has
1b6b0 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 8 entries. Supp
1b6c0 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 ose the result t
1b6d0 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a able is stored.*
1b6e0 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 * in an array na
1b6f0 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 mes azResult. T
1b700 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c hen azResult hol
1b710 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a ds this content:
1b720 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1b730 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 te><pre>.**
1b740 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1b750 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 0] = "Name";.**
1b760 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1b770 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a #91;1] = "Age";.
1b780 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1b790 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 lt[2] = "Ali
1b7a0 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 ce";.** a
1b7b0 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d zResult[3] =
1b7c0 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 "43";.**
1b7d0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d azResult[4]
1b7e0 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 = "Bob";.**
1b7f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1b800 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 ;5] = "28";.**
1b810 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1b820 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 91;6] = "Cindy";
1b830 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1b840 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 ult[7] = "21
1b850 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c ";.** </pre></bl
1b860 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a ockquote>)^.**.*
1b870 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 * ^The sqlite3_g
1b880 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 et_table() funct
1b890 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e ion evaluates on
1b8a0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d e or more.** sem
1b8b0 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 icolon-separated
1b8c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
1b8d0 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d in the zero-term
1b8e0 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 inated UTF-8.**
1b8f0 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e string of its 2n
1b900 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 d parameter and
1b910 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 returns a result
1b920 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a table to the.**
1b930 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 pointer given i
1b940 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 n its 3rd parame
1b950 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 ter..**.** After
1b960 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
1b970 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
1b980 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 th the result fr
1b990 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 om sqlite3_get_t
1b9a0 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 able(),.** it mu
1b9b0 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 st pass the resu
1b9c0 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 lt table pointer
1b9d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 to sqlite3_free
1b9e0 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 _table() in orde
1b9f0 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 r to.** release
1ba00 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 the memory that
1ba10 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 was malloced. B
1ba20 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 ecause of the wa
1ba30 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 y the.** [sqlite
1ba40 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 3_malloc()] happ
1ba50 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 ens within sqlit
1ba60 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 e3_get_table(),
1ba70 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 the calling.** f
1ba80 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 unction must not
1ba90 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 try to call [sq
1baa0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 lite3_free()] di
1bab0 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a rectly. Only.**
1bac0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 [sqlite3_free_t
1bad0 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 able()] is able
1bae0 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d to release the m
1baf0 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 emory properly a
1bb00 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a nd safely..**.**
1bb10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
1bb20 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 _table() interfa
1bb30 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 ce is implemente
1bb40 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 d as a wrapper a
1bb50 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 round.** [sqlite
1bb60 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 3_exec()]. The
1bb70 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
1bb80 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 e() routine does
1bb90 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 not have access
1bba0 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 .** to any inter
1bbb0 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 nal data structu
1bbc0 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 res of SQLite.
1bbd0 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 It uses only the
1bbe0 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 public.** inter
1bbf0 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 face defined her
1bc00 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 e. As a consequ
1bc10 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 ence, errors tha
1bc20 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a t occur in the.*
1bc30 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 * wrapper layer
1bc40 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 outside of the i
1bc50 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 nternal [sqlite3
1bc60 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 _exec()] call ar
1bc70 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 e not.** reflect
1bc80 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 ed in subsequent
1bc90 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
1bca0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 e3_errcode()] or
1bcb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 .** [sqlite3_err
1bcc0 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 msg()]..*/.SQLIT
1bcd0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
1bce0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
1bcf0 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 _get_table(. sq
1bd00 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
1bd10 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
1bd20 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
1bd30 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
1bd40 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 /* SQL to be
1bd50 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 evaluated */. c
1bd60 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 har ***pazResult
1bd70 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 , /* Results
1bd80 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a of the query */.
1bd90 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 int *pnRow,
1bda0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 /* Numbe
1bdb0 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 r of result rows
1bdc0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
1bdd0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e . int *pnColumn
1bde0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 , /* Numb
1bdf0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c er of result col
1be00 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 umns written her
1be10 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a e */. char **pz
1be20 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 Errmsg /*
1be30 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 Error msg writte
1be40 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c n here */.);.SQL
1be50 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c ITE_API void SQL
1be60 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
1be70 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 te3_free_table(c
1be80 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a har **result);..
1be90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1bea0 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 Formatted String
1beb0 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 Printing Functi
1bec0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ons.**.** These
1bed0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 routines are wor
1bee0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 k-alikes of the
1bef0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c "printf()" famil
1bf00 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a y of functions.*
1bf10 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 * from the stand
1bf20 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a ard C library..*
1bf30 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
1bf40 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 understand most
1bf50 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b of the common K
1bf60 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 &R formatting op
1bf70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 tions,.** plus s
1bf80 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e ome additional n
1bf90 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d on-standard form
1bfa0 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 ats, detailed be
1bfb0 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 low..** Note tha
1bfc0 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f t some of the mo
1bfd0 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 re obscure forma
1bfe0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 tting options fr
1bff0 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c om recent.** C-l
1c000 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 ibrary standards
1c010 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f are omitted fro
1c020 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 m this implement
1c030 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ation..**.** ^Th
1c040 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 e sqlite3_mprint
1c050 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f f() and sqlite3_
1c060 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 vmprintf() routi
1c070 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a nes write their.
1c080 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 ** results into
1c090 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
1c0a0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
1c0b0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 lloc()]..** The
1c0c0 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 strings returned
1c0d0 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f by these two ro
1c0e0 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 utines should be
1c0f0 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 .** released by
1c100 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1c110 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 . ^Both routine
1c120 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 s return a.** NU
1c130 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 LL pointer if [s
1c140 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
1c150 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c is unable to al
1c160 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a locate enough.**
1c170 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 memory to hold
1c180 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
1c190 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ring..**.** ^(Th
1c1a0 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e e sqlite3_snprin
1c1b0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 tf() routine is
1c1c0 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 similar to "snpr
1c1d0 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 intf()" from.**
1c1e0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c the standard C l
1c1f0 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 ibrary. The res
1c200 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 ult is written i
1c210 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 nto the.** buffe
1c220 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 r supplied as th
1c230 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1c240 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 er whose size is
1c250 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 given by.** the
1c260 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
1c270 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 . Note that the
1c280 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 order of the.**
1c290 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 first two parame
1c2a0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 ters is reversed
1c2b0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 from snprintf()
1c2c0 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a .)^ This is an.
1c2d0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 ** historical ac
1c2e0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e cident that cann
1c2f0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 ot be fixed with
1c300 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 out breaking.**
1c310 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
1c320 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 ibility. ^(Note
1c330 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 also that sqlit
1c340 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
1c350 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
1c360 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 er to its buffer
1c370 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
1c380 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 number of.** cha
1c390 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 racters actually
1c3a0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
1c3b0 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 e buffer.)^ We
1c3c0 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 admit that.** th
1c3d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
1c3e0 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 acters written w
1c3f0 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 ould be a more u
1c400 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 seful return.**
1c410 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e value but we can
1c420 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 not change the i
1c430 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
1c440 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
1c450 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f f().** now witho
1c460 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 ut breaking comp
1c470 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a atibility..**.**
1c480 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 ^As long as the
1c490 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 buffer size is
1c4a0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 greater than zer
1c4b0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 o, sqlite3_snpri
1c4c0 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 ntf().** guarant
1c4d0 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 ees that the buf
1c4e0 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 fer is always ze
1c4f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 ro-terminated.
1c500 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 ^The first.** pa
1c510 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 rameter "n" is t
1c520 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 he total size of
1c530 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 the buffer, inc
1c540 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 luding space for
1c550 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 .** the zero ter
1c560 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 minator. So the
1c570 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 longest string
1c580 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 that can be comp
1c590 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 letely.** writte
1c5a0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 n will be n-1 ch
1c5b0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 aracters..**.**
1c5c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e ^The sqlite3_vsn
1c5d0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
1c5e0 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 is a varargs ve
1c5f0 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 rsion of sqlite3
1c600 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a _snprintf()..**.
1c610 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
1c620 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 s all implement
1c630 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 some additional
1c640 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 formatting.** op
1c650 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 tions that are u
1c660 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 seful for constr
1c670 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 ucting SQL state
1c680 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 ments..** All of
1c690 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 the usual print
1c6a0 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f f() formatting o
1c6b0 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 ptions apply. I
1c6c0 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 n addition, ther
1c6d0 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 e.** is are "%q"
1c6e0 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 , "%Q", "%w" and
1c6f0 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a "%z" options..*
1c700 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 *.** ^(The %q op
1c710 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 tion works like
1c720 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 %s in that it su
1c730 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d bstitutes a nul-
1c740 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 terminated.** st
1c750 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 ring from the ar
1c760 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 gument list. Bu
1c770 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 t %q also double
1c780 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 s every '\'' cha
1c790 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 racter..** %q is
1c7a0 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 designed for us
1c7b0 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e e inside a strin
1c7c0 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 g literal.)^ By
1c7d0 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 doubling each '
1c7e0 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 \''.** character
1c7f0 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 it escapes that
1c800 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 character and a
1c810 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 llows it to be i
1c820 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 nserted into.**
1c830 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a the string..**.*
1c840 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 * For example, a
1c850 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 ssume the string
1c860 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 variable zText
1c870 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 contains text as
1c880 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
1c890 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1c8a0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 >.** char *zTex
1c8b0 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 t = "It's a happ
1c8c0 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 y day!";.** </pr
1c8d0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1c8e0 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 **.** One can us
1c8f0 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 e this text in a
1c900 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 n SQL statement
1c910 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
1c920 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1c930 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 re>.** char *zS
1c940 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 QL = sqlite3_mpr
1c950 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 intf("INSERT INT
1c960 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 O table VALUES('
1c970 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a %q')", zText);.*
1c980 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * sqlite3_exec(
1c990 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 db, zSQL, 0, 0,
1c9a0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 0);.** sqlite3_
1c9b0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c free(zSQL);.** <
1c9c0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1c9d0 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 e>.**.** Because
1c9e0 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 the %q format s
1c9f0 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 tring is used, t
1ca00 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 he '\'' characte
1ca10 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 r in zText.** is
1ca20 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 escaped and the
1ca30 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 SQL generated i
1ca40 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
1ca50 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1ca60 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 <pre>.** INSERT
1ca70 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c INTO table1 VAL
1ca80 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 UES('It''s a hap
1ca90 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 py day!').** </p
1caa0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1cab0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 .**.** This is c
1cac0 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 orrect. Had we
1cad0 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 used %s instead
1cae0 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 of %q, the gener
1caf0 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c ated SQL.** woul
1cb00 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 d have looked li
1cb10 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c ke this:.**.** <
1cb20 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1cb30 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f .** INSERT INTO
1cb40 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 table1 VALUES('
1cb50 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 It's a happy day
1cb60 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f !');.** </pre></
1cb70 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
1cb80 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 * This second ex
1cb90 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 ample is an SQL
1cba0 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 syntax error. A
1cbb0 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 s a general rule
1cbc0 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 you should.** a
1cbd0 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 lways use %q ins
1cbe0 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 tead of %s when
1cbf0 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 inserting text i
1cc00 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 nto a string lit
1cc10 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 eral..**.** ^(Th
1cc20 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b e %Q option work
1cc30 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 s like %q except
1cc40 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 it also adds si
1cc50 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 ngle quotes arou
1cc60 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 nd.** the outsid
1cc70 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 e of the total s
1cc80 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e tring. Addition
1cc90 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 ally, if the par
1cca0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a ameter in the.**
1ccb0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 argument list i
1ccc0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
1ccd0 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 , %Q substitutes
1cce0 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 the text "NULL"
1ccf0 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e (without.** sin
1cd00 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 gle quotes).)^
1cd10 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c So, for example,
1cd20 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a one could say:.
1cd30 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1cd40 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 e><pre>.** char
1cd50 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 *zSQL = sqlite3
1cd60 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 _mprintf("INSERT
1cd70 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 INTO table VALU
1cd80 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b ES(%Q)", zText);
1cd90 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 .** sqlite3_exe
1cda0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 c(db, zSQL, 0, 0
1cdb0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 , 0);.** sqlite
1cdc0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 3_free(zSQL);.**
1cdd0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
1cde0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ote>.**.** The c
1cdf0 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 ode above will r
1ce00 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 ender a correct
1ce10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
1ce20 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 the zSQL.** var
1ce30 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 iable even if th
1ce40 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 e zText variable
1ce50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
1ce60 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 er..**.** ^(The
1ce70 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 "%w" formatting
1ce80 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 option is like "
1ce90 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74 20 %q" except that
1cea0 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a it expects to.**
1ceb0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 be contained wi
1cec0 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 thin double-quot
1ced0 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 es instead of si
1cee0 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 ngle quotes, and
1cef0 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 it.** escapes t
1cf00 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 he double-quote
1cf10 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 character instea
1cf20 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d d of the single-
1cf30 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 quote.** charact
1cf40 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 er.)^ The "%w"
1cf50 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f formatting optio
1cf60 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f n is intended fo
1cf70 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 r safely inserti
1cf80 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 ng.** table and
1cf90 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 column names int
1cfa0 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 o a constructed
1cfb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a SQL statement..*
1cfc0 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 *.** ^(The "%z"
1cfd0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f formatting optio
1cfe0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 n works like "%s
1cff0 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a " but with the.*
1d000 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 * addition that
1d010 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 after the string
1d020 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 has been read a
1d030 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a nd copied into.*
1d040 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 * the result, [s
1d050 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 qlite3_free()] i
1d060 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 s called on the
1d070 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a input string.)^.
1d080 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 */.SQLITE_API ch
1d090 61 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c ar *SQLITE_CDECL
1d0a0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
1d0b0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e (const char*,...
1d0c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 );.SQLITE_API ch
1d0d0 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 ar *SQLITE_STDCA
1d0e0 4c 4c 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 LL sqlite3_vmpri
1d0f0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c ntf(const char*,
1d100 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 va_list);.SQLIT
1d110 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 E_API char *SQLI
1d120 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 TE_CDECL sqlite3
1d130 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 _snprintf(int,ch
1d140 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
1d150 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ...);.SQLITE_AP
1d160 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 I char *SQLITE_S
1d170 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
1d180 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 snprintf(int,cha
1d190 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 r*,const char*,
1d1a0 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a va_list);../*.**
1d1b0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
1d1c0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 y Allocation Sub
1d1d0 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 system.**.** The
1d1e0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 SQLite core use
1d1f0 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f s these three ro
1d200 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f utines for all o
1d210 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 f its own.** int
1d220 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c ernal memory all
1d230 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 ocation needs. "
1d240 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 Core" in the pre
1d250 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a vious sentence.*
1d260 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 * does not inclu
1d270 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 de operating-sys
1d280 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 tem specific VFS
1d290 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
1d2a0 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 The.** Windows
1d2b0 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 VFS uses native
1d2c0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 malloc() and fr
1d2d0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 ee() for some op
1d2e0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
1d2f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^The sqlite3_mal
1d300 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 loc() routine re
1d310 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
1d320 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 to a block.** of
1d330 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 memory at least
1d340 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 N bytes in leng
1d350 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 th, where N is t
1d360 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a he parameter..**
1d370 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^If sqlite3_mal
1d380 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 loc() is unable
1d390 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 to obtain suffic
1d3a0 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d ient free.** mem
1d3b0 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 ory, it returns
1d3c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
1d3d0 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 ^If the paramet
1d3e0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 er N to.** sqlit
1d3f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a e3_malloc() is z
1d400 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ero or negative
1d410 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c then sqlite3_mal
1d420 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a loc() returns.**
1d430 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1d440 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1d450 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 te3_malloc64(N)
1d460 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 routine works ju
1d470 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 st like.** sqlit
1d480 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 e3_malloc(N) exc
1d490 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e ept that N is an
1d4a0 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 unsigned 64-bit
1d4b0 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 integer instead
1d4c0 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 .** of a signed
1d4d0 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 32-bit integer..
1d4e0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 **.** ^Calling s
1d4f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 qlite3_free() wi
1d500 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 th a pointer pre
1d510 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 viously returned
1d520 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d .** by sqlite3_m
1d530 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 alloc() or sqlit
1d540 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c e3_realloc() rel
1d550 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 eases that memor
1d560 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 y so.** that it
1d570 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e might be reused.
1d580 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 ^The sqlite3_f
1d590 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ree() routine is
1d5a0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 .** a no-op if i
1d5b0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
1d5c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 NULL pointer. P
1d5d0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f assing a NULL po
1d5e0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 inter.** to sqli
1d5f0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 te3_free() is ha
1d600 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 rmless. After b
1d610 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f eing freed, memo
1d620 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 ry.** should nei
1d630 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 ther be read nor
1d640 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 written. Even
1d650 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 reading previous
1d660 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f ly freed.** memo
1d670 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 ry might result
1d680 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f in a segmentatio
1d690 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 n fault or other
1d6a0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a severe error..*
1d6b0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 * Memory corrupt
1d6c0 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 ion, a segmentat
1d6d0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 ion fault, or ot
1d6e0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 her severe error
1d6f0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 .** might result
1d700 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 if sqlite3_free
1d710 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 () is called wit
1d720 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 h a non-NULL poi
1d730 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 nter that.** was
1d740 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 not obtained fr
1d750 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
1d760 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 c() or sqlite3_r
1d770 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 ealloc()..**.**
1d780 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 ^The sqlite3_rea
1d790 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 lloc(X,N) interf
1d7a0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
1d7b0 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f resize a.** prio
1d7c0 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 r memory allocat
1d7d0 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c ion X to be at l
1d7e0 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a east N bytes..**
1d7f0 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d ^If the X param
1d800 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
1d810 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 realloc(X,N).**
1d820 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
1d830 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 r then its behav
1d840 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c ior is identical
1d850 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 to calling.** s
1d860 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 qlite3_malloc(N)
1d870 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 ..** ^If the N p
1d880 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
1d890 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1d8a0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e is zero or.** n
1d8b0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 egative then the
1d8c0 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 behavior is exa
1d8d0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 ctly the same as
1d8e0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
1d8f0 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 te3_free(X)..**
1d900 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 ^sqlite3_realloc
1d910 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 (X,N) returns a
1d920 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d pointer to a mem
1d930 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
1d940 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 * of at least N
1d950 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 bytes in size or
1d960 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 NULL if insuffi
1d970 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 cient memory is
1d980 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 available..** ^I
1d990 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 f M is the size
1d9a0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
1d9b0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 ocation, then mi
1d9c0 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 n(N,M) bytes.**
1d9d0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
1d9e0 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 ocation are copi
1d9f0 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 ed into the begi
1da00 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 nning of buffer
1da10 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 returned.** by s
1da20 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
1da30 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f ,N) and the prio
1da40 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 r allocation is
1da50 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 freed..** ^If sq
1da60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
1da70 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 N) returns NULL
1da80 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 and N is positiv
1da90 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 e, then the.** p
1daa0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
1dab0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a is not freed..**
1dac0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1dad0 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 _realloc64(X,N)
1dae0 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 interfaces works
1daf0 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 the same as.**
1db00 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1db10 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 X,N) except that
1db20 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 N is a 64-bit u
1db30 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 nsigned integer
1db40 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 instead.** of a
1db50 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 32-bit signed in
1db60 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 teger..**.** ^If
1db70 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 X is a memory a
1db80 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f llocation previo
1db90 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 usly obtained fr
1dba0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
1dbb0 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f c(),.** sqlite3_
1dbc0 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 malloc64(), sqli
1dbd0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f te3_realloc(), o
1dbe0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
1dbf0 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 c64(), then.** s
1dc00 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 qlite3_msize(X)
1dc10 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 returns the size
1dc20 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 of that memory
1dc30 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 allocation in by
1dc40 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c tes..** ^The val
1dc50 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
1dc60 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 qlite3_msize(X)
1dc70 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 might be larger
1dc80 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a than the number.
1dc90 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 ** of bytes requ
1dca0 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 ested when X was
1dcb0 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 allocated. ^If
1dcc0 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 X is a NULL poi
1dcd0 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c nter then.** sql
1dce0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 ite3_msize(X) re
1dcf0 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 turns zero. If
1dd00 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 X points to some
1dd10 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f thing that is no
1dd20 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 t.** the beginni
1dd30 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c ng of memory all
1dd40 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 ocation, or if i
1dd50 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f t points to a fo
1dd60 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 rmerly.** valid
1dd70 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1dd80 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 n that has now b
1dd90 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 een freed, then
1dda0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 the behavior.**
1ddb0 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 of sqlite3_msize
1ddc0 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 (X) is undefined
1ddd0 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 and possibly ha
1dde0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rmful..**.** ^Th
1ddf0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 e memory returne
1de00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c d by sqlite3_mal
1de10 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 loc(), sqlite3_r
1de20 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c ealloc(),.** sql
1de30 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c ite3_malloc64(),
1de40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 and sqlite3_rea
1de50 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 lloc64().** is a
1de60 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f lways aligned to
1de70 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 at least an 8 b
1de80 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 yte boundary, or
1de90 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 to a.** 4 byte
1dea0 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 boundary if the
1deb0 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 [SQLITE_4_BYTE_A
1dec0 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 LIGNED_MALLOC] c
1ded0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f ompile-time.** o
1dee0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a ption is used..*
1def0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 *.** In SQLite v
1df00 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 ersion 3.5.0 and
1df10 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 3.5.1, it was p
1df20 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e ossible to defin
1df30 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f e.** the SQLITE_
1df40 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f OMIT_MEMORY_ALLO
1df50 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 CATION which wou
1df60 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 ld cause the bui
1df70 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 lt-in.** impleme
1df80 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 ntation of these
1df90 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
1dfa0 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 omitted. That c
1dfb0 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 apability.** is
1dfc0 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 no longer provid
1dfd0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d ed. Only built-
1dfe0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
1dff0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 tors can be used
1e000 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f ..**.** Prior to
1e010 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
1e020 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 3.7.10, the Wind
1e030 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 ows OS interface
1e040 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a layer called.**
1e050 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c the system mall
1e060 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
1e070 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f directly when co
1e080 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 nverting.** file
1e090 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 names between th
1e0a0 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 e UTF-8 encoding
1e0b0 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a used by SQLite.
1e0c0 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 ** and whatever
1e0d0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e filename encodin
1e0e0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 g is used by the
1e0f0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 particular Wind
1e100 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 ows.** installat
1e110 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c ion. Memory all
1e120 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 ocation errors w
1e130 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 ere detected, bu
1e140 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 t.** they were r
1e150 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 eported back as
1e160 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e [SQLITE_CANTOPEN
1e170 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ] or.** [SQLITE_
1e180 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 IOERR] rather th
1e190 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d an [SQLITE_NOMEM
1e1a0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 ]..**.** The poi
1e1b0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 nter arguments t
1e1c0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
1e1d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1e1e0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 realloc()].** mu
1e1f0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c st be either NUL
1e200 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 L or else pointe
1e210 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d rs obtained from
1e220 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f a prior.** invo
1e230 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 cation of [sqlit
1e240 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 e3_malloc()] or
1e250 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
1e260 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a ()] that have.**
1e270 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 not yet been re
1e280 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 leased..**.** Th
1e290 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
1e2a0 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 st not read or w
1e2b0 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 rite any part of
1e2c0 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d .** a block of m
1e2d0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 emory after it h
1e2e0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 as been released
1e2f0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
1e300 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 e3_free()] or [s
1e310 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1e320 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
1e330 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
1e340 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 DCALL sqlite3_ma
1e350 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 lloc(int);.SQLIT
1e360 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 E_API void *SQLI
1e370 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
1e380 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 e3_malloc64(sqli
1e390 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c te3_uint64);.SQL
1e3a0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 ITE_API void *SQ
1e3b0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1e3c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 ite3_realloc(voi
1e3d0 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 d*, int);.SQLITE
1e3e0 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 _API void *SQLIT
1e3f0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
1e400 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 3_realloc64(void
1e410 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 *, sqlite3_uint6
1e420 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 4);.SQLITE_API v
1e430 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 oid SQLITE_STDCA
1e440 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 LL sqlite3_free(
1e450 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 void*);.SQLITE_A
1e460 50 49 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 PI sqlite3_uint6
1e470 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 4 SQLITE_STDCALL
1e480 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 sqlite3_msize(v
1e490 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
1e4a0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
1e4b0 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 llocator Statist
1e4c0 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ics.**.** SQLite
1e4d0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 provides these
1e4e0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 two interfaces f
1e4f0 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 or reporting on
1e500 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 the status.** of
1e510 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 the [sqlite3_ma
1e520 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 lloc()], [sqlite
1e530 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 3_free()], and [
1e540 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1e550 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 )].** routines,
1e560 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 which form the b
1e570 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
1e580 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
1e590 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 tem..**.** ^The
1e5a0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
1e5b0 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 used()] routine
1e5c0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
1e5d0 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f er of bytes.** o
1e5e0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 f memory current
1e5f0 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 ly outstanding (
1e600 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 malloced but not
1e610 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 freed)..** ^The
1e620 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1e630 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f _highwater()] ro
1e640 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
1e650 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c e maximum.** val
1e660 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d ue of [sqlite3_m
1e670 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 emory_used()] si
1e680 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 nce the high-wat
1e690 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c er mark.** was l
1e6a0 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 ast reset. ^The
1e6b0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 values returned
1e6c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d by [sqlite3_mem
1e6d0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a ory_used()] and.
1e6e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ** [sqlite3_memo
1e6f0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 ry_highwater()]
1e700 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 include any over
1e710 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 head.** added by
1e720 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 SQLite in its i
1e730 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
1e740 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1e750 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 ()],.** but not
1e760 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 overhead added b
1e770 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c y the any underl
1e780 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 ying system libr
1e790 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ary.** routines
1e7a0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 that [sqlite3_ma
1e7b0 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c lloc()] may call
1e7c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d ..**.** ^The mem
1e7d0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d ory high-water m
1e7e0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 ark is reset to
1e7f0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 the current valu
1e800 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 e of.** [sqlite3
1e810 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
1e820 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 if and only if t
1e830 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a he parameter to.
1e840 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ** [sqlite3_memo
1e850 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 ry_highwater()]
1e860 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 is true. ^The v
1e870 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a alue returned.**
1e880 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d by [sqlite3_mem
1e890 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 ory_highwater(1)
1e8a0 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 ] is the high-wa
1e8b0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f ter mark.** prio
1e8c0 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a r to the reset..
1e8d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 */.SQLITE_API sq
1e8e0 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 lite3_int64 SQLI
1e8f0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
1e900 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 e3_memory_used(v
1e910 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
1e920 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 sqlite3_int64 S
1e930 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
1e940 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
1e950 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 hwater(int reset
1e960 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Flag);../*.** CA
1e970 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 PI3REF: Pseudo-R
1e980 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e andom Number Gen
1e990 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c erator.**.** SQL
1e9a0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 ite contains a h
1e9b0 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 igh-quality pseu
1e9c0 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 do-random number
1e9d0 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 generator (PRNG
1e9e0 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c ) used to.** sel
1e9f0 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 ect random [ROWI
1ea00 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e D | ROWIDs] when
1ea10 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 inserting new r
1ea20 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 ecords into a ta
1ea30 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 ble that.** alre
1ea40 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 ady uses the lar
1ea50 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 gest possible [R
1ea60 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 OWID]. The PRNG
1ea70 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f is also used fo
1ea80 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 r.** the build-i
1ea90 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 n random() and r
1eaa0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 andomblob() SQL
1eab0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 functions. This
1eac0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 interface allow
1ead0 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e s.** application
1eae0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
1eaf0 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 same PRNG for ot
1eb00 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a her purposes..**
1eb10 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 .** ^A call to t
1eb20 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 his routine stor
1eb30 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 es N bytes of ra
1eb40 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 ndomness into bu
1eb50 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 ffer P..** ^The
1eb60 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 P parameter can
1eb70 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 be a NULL pointe
1eb80 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 r..**.** ^If thi
1eb90 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f s routine has no
1eba0 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c t been previousl
1ebb0 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 y called or if t
1ebc0 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 he previous.** c
1ebd0 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 all had N less t
1ebe0 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c han one or a NUL
1ebf0 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c L pointer for P,
1ec00 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 then the PRNG i
1ec10 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e s.** seeded usin
1ec20 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 g randomness obt
1ec30 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 ained from the x
1ec40 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f Randomness metho
1ec50 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 d of.** the defa
1ec60 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
1ec70 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 ] object..** ^If
1ec80 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 the previous ca
1ec90 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 ll to this routi
1eca0 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 ne had an N of 1
1ecb0 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a or more and a.*
1ecc0 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 * non-NULL P the
1ecd0 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e n the pseudo-ran
1ece0 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 domness is gener
1ecf0 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c ated.** internal
1ed00 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 ly and without r
1ed10 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b ecourse to the [
1ed20 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 sqlite3_vfs] xRa
1ed30 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 ndomness.** meth
1ed40 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 od..*/.SQLITE_AP
1ed50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 I void SQLITE_ST
1ed60 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 61 DCALL sqlite3_ra
1ed70 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 ndomness(int N,
1ed80 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a void *P);../*.**
1ed90 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
1eda0 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a le-Time Authoriz
1edb0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a ation Callbacks.
1edc0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
1edd0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 e3.**.** ^This r
1ede0 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 outine registers
1edf0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 an authorizer c
1ee00 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 allback with a p
1ee10 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 articular.** [da
1ee20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1ee30 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 n], supplied in
1ee40 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
1ee50 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 nt..** ^The auth
1ee60 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1ee70 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 is invoked as SQ
1ee80 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
1ee90 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a being compiled.
1eea0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 ** by [sqlite3_p
1eeb0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 repare()] or its
1eec0 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 variants [sqlit
1eed0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1eee0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 ,.** [sqlite3_pr
1eef0 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b epare16()] and [
1ef00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1ef10 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 6_v2()]. ^At va
1ef20 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 rious.** points
1ef30 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 during the compi
1ef40 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 lation process,
1ef50 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e as logic is bein
1ef60 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 g created.** to
1ef70 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 perform various
1ef80 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 actions, the aut
1ef90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1efa0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a is invoked to.*
1efb0 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 * see if those a
1efc0 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 ctions are allow
1efd0 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 ed. ^The author
1efe0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 izer callback sh
1eff0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b ould.** return [
1f000 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c SQLITE_OK] to al
1f010 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 low the action,
1f020 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
1f030 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a to disallow the.
1f040 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 ** specific acti
1f050 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 on but allow the
1f060 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
1f070 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 o continue to be
1f080 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 .** compiled, or
1f090 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 [SQLITE_DENY] t
1f0a0 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 o cause the enti
1f0b0 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 re SQL statement
1f0c0 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 to be.** reject
1f0d0 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 ed with an error
1f0e0 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f . ^If the autho
1f0f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
1f100 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 eturns.** any va
1f110 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b lue other than [
1f120 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 SQLITE_IGNORE],
1f130 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 [SQLITE_OK], or
1f140 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a [SQLITE_DENY].**
1f150 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 then the [sqlit
1f160 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1f170 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 or equivalent c
1f180 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
1f190 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 ed.** the author
1f1a0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 izer will fail w
1f1b0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ith an error mes
1f1c0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e sage..**.** When
1f1d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
1f1e0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
1f1f0 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 ], that means th
1f200 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 e operation.** r
1f210 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 equested is ok.
1f220 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 ^When the callb
1f230 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
1f240 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a ITE_DENY], the.*
1f250 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
1f260 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 re_v2()] or equi
1f270 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 valent call that
1f280 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a triggered the.*
1f290 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c * authorizer wil
1f2a0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 l fail with an e
1f2b0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 rror message exp
1f2c0 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 laining that.**
1f2d0 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 access is denied
1f2e0 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 . .**.** ^The fi
1f2f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
1f300 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1f310 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f callback is a co
1f320 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a py of the third.
1f330 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ** parameter to
1f340 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f the sqlite3_set_
1f350 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 authorizer() int
1f360 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 erface. ^The sec
1f370 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ond parameter.**
1f380 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
1f390 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b is an integer [
1f3a0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 SQLITE_COPY | ac
1f3b0 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 tion code] that
1f3c0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 specifies.** the
1f3d0 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 particular acti
1f3e0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 on to be authori
1f3f0 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 zed. ^The third
1f400 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 through sixth pa
1f410 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 rameters.** to t
1f420 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 he callback are
1f430 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1f440 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e strings that con
1f450 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a tain additional.
1f460 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 ** details about
1f470 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 the action to b
1f480 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a e authorized..**
1f490 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 .** ^If the acti
1f4a0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 on code is [SQLI
1f4b0 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 TE_READ].** and
1f4c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
1f4d0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e urns [SQLITE_IGN
1f4e0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a ORE] then the.**
1f4f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1f500 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 ment] statement
1f510 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 is constructed t
1f520 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 o substitute.**
1f530 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 a NULL value in
1f540 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 place of the tab
1f550 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 le column that w
1f560 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 ould have.** bee
1f570 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 n read if [SQLIT
1f580 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 E_OK] had been r
1f590 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 eturned. The [S
1f5a0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a QLITE_IGNORE].**
1f5b0 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 return can be u
1f5c0 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 sed to deny an u
1f5d0 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 ntrusted user ac
1f5e0 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 cess to individu
1f5f0 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 al.** columns of
1f600 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 a table..** ^If
1f610 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 the action code
1f620 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 is [SQLITE_DELE
1f630 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c TE] and the call
1f640 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 back returns.**
1f650 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
1f660 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 then the [DELETE
1f670 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 ] operation proc
1f680 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 eeds but the.**
1f690 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 [truncate optimi
1f6a0 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 zation] is disab
1f6b0 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 led and all rows
1f6c0 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 are deleted ind
1f6d0 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a ividually..**.**
1f6e0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 An authorizer i
1f6f0 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c s used when [sql
1f700 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 ite3_prepare | p
1f710 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c reparing].** SQL
1f720 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d statements from
1f730 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f an untrusted so
1f740 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 urce, to ensure
1f750 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 that the SQL sta
1f760 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f tements.** do no
1f770 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 t try to access
1f780 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f data they are no
1f790 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 t allowed to see
1f7a0 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 , or that they d
1f7b0 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 o not.** try to
1f7c0 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 execute maliciou
1f7d0 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 s statements tha
1f7e0 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 t damage the dat
1f7f0 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 abase. For.** e
1f800 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 xample, an appli
1f810 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 cation may allow
1f820 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 a user to enter
1f830 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 arbitrary.** SQ
1f840 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 L queries for ev
1f850 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 aluation by a da
1f860 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 tabase. But the
1f870 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 application doe
1f880 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 s.** not want th
1f890 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c e user to be abl
1f8a0 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 e to make arbitr
1f8b0 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 ary changes to t
1f8c0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 he.** database.
1f8d0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 An authorizer c
1f8e0 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 ould then be put
1f8f0 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 in place while
1f900 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 the.** user-ente
1f910 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 red SQL is being
1f920 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1f930 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 e | prepared] th
1f940 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 at.** disallows
1f950 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 everything excep
1f960 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 t [SELECT] state
1f970 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 ments..**.** App
1f980 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e lications that n
1f990 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 eed to process S
1f9a0 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 QL from untruste
1f9b0 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 d sources.** mig
1f9c0 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 ht also consider
1f9d0 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 lowering resour
1f9e0 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 ce limits using
1f9f0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
1fa00 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e ].** and limitin
1fa10 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 g database size
1fa20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 using the [max_p
1fa30 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 age_count] [PRAG
1fa40 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 MA].** in additi
1fa50 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 on to using an a
1fa60 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a uthorizer..**.**
1fa70 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 ^(Only a single
1fa80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 authorizer can
1fa90 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 be in place on a
1faa0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1fab0 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d tion.** at a tim
1fac0 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f e. Each call to
1fad0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
1fae0 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 horizer override
1faf0 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 s the.** previou
1fb00 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 s call.)^ ^Disa
1fb10 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a ble the authoriz
1fb20 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 er by installing
1fb30 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b a NULL callback
1fb40 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 ..** The authori
1fb50 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 zer is disabled
1fb60 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a by default..**.*
1fb70 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
1fb80 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e callback must n
1fb90 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 ot do anything t
1fba0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a hat will modify.
1fbb0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
1fbc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
1fbd0 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 invoked the auth
1fbe0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e orizer callback.
1fbf0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
1fc00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1fc10 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
1fc20 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
1fc30 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
1fc40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1fc50 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
1fc60 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
1fc70 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
1fc80 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b h..**.** ^When [
1fc90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1fca0 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f v2()] is used to
1fcb0 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 prepare a state
1fcc0 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 ment, the.** sta
1fcd0 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 tement might be
1fce0 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 re-prepared duri
1fcf0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ng [sqlite3_step
1fd00 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a ()] due to a .**
1fd10 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 schema change.
1fd20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c Hence, the appl
1fd30 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 ication should e
1fd40 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a nsure that the.*
1fd50 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 * correct author
1fd60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 izer callback re
1fd70 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 mains in place d
1fd80 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 uring the [sqlit
1fd90 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a e3_step()]..**.*
1fda0 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 * ^Note that the
1fdb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1fdc0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
1fdd0 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b only during.** [
1fde0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
1fdf0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
1fe00 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 ts. Authorizati
1fe10 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 on is not.** per
1fe20 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 formed during st
1fe30 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 atement evaluati
1fe40 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 on in [sqlite3_s
1fe50 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a tep()], unless.*
1fe60 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 * as stated in t
1fe70 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 he previous para
1fe80 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 graph, sqlite3_s
1fe90 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a tep() invokes.**
1fea0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
1feb0 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 _v2() to reprepa
1fec0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 re a statement a
1fed0 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 fter a schema ch
1fee0 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ange..*/.SQLITE_
1fef0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
1ff00 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 TDCALL sqlite3_s
1ff10 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 et_authorizer(.
1ff20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 sqlite3*,. int
1ff30 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c (*xAuth)(void*,
1ff40 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c int,const char*,
1ff50 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
1ff60 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
1ff70 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 ar*),. void *pU
1ff80 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a serData.);../*.*
1ff90 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
1ffa0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f orizer Return Co
1ffb0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
1ffc0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1ffd0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
1ffe0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
1fff0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 tion] must.** re
20000 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c turn either [SQL
20010 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f ITE_OK] or one o
20020 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 f these two cons
20030 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a tants in order.*
20040 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 * to signal SQLi
20050 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f te whether or no
20060 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 t the action is
20070 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 permitted. See
20080 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
20090 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
200a0 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 authorizer docu
200b0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 mentation] for a
200c0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
200d0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
200e0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 Note that SQLITE
200f0 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 _IGNORE is also
20100 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c used as a [confl
20110 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d ict resolution m
20120 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 ode].** returned
20130 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 from the [sqlit
20140 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c e3_vtab_on_confl
20150 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ict()] interface
20160 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
20170 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f ITE_DENY 1 /
20180 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 * Abort the SQL
20190 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 statement with a
201a0 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 n error */.#defi
201b0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 ne SQLITE_IGNORE
201c0 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 2 /* Don't al
201d0 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 low access, but
201e0 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 don't generate a
201f0 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a n error */../*.*
20200 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
20210 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f orizer Action Co
20220 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
20230 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
20240 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 rizer()] interfa
20250 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 ce registers a c
20260 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
20270 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f .** that is invo
20280 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 ked to authorize
20290 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 certain SQL sta
202a0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 tement actions.
202b0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 The.** second p
202c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
202d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 callback is an i
202e0 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 nteger code that
202f0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 specifies.** wh
20300 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 at action is bei
20310 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ng authorized.
20320 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e These are the in
20330 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 teger action cod
20340 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 es that.** the a
20350 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
20360 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 ck may be passed
20370 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 ..**.** These ac
20380 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 tion code values
20390 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 signify what ki
203a0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 nd of operation
203b0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 is to be.** auth
203c0 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 orized. The 3rd
203d0 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 and 4th paramet
203e0 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f ers to the autho
203f0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c rization.** call
20400 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 back function wi
20410 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 ll be parameters
20420 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 or NULL dependi
20430 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 ng on which of t
20440 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 hese.** codes is
20450 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 used as the sec
20460 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 ond parameter.
20470 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 ^(The 5th parame
20480 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 ter to the.** au
20490 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
204a0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 k is the name of
204b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 the database ("
204c0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a main", "temp",.*
204d0 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 * etc.) if appli
204e0 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 cable.)^ ^The 6
204f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
20500 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
20510 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 allback.** is th
20520 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e e name of the in
20530 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 ner-most trigger
20540 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 or view that is
20550 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
20560 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 .** the access a
20570 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 ttempt or NULL i
20580 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 f this access at
20590 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c tempt is directl
205a0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 y from.** top-le
205b0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f vel SQL code..*/
205c0 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ./**************
205d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
205e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 ************* 3r
205f0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 d ************ 4
20600 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a th ***********/.
20610 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
20620 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 REATE_INDEX
20630 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 1 /* Inde
20640 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
20650 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
20660 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
20670 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 EATE_TABLE
20680 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 2 /* Table
20690 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
206a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
206b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
206c0 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 ATE_TEMP_INDEX
206d0 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 3 /* Index
206e0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
206f0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
20700 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
20710 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 TE_TEMP_TABLE
20720 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 4 /* Table N
20730 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
20740 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
20750 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
20760 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 E_TEMP_TRIGGER
20770 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 5 /* Trigger
20780 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
20790 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
207a0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
207b0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 _TEMP_VIEW
207c0 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 6 /* View Name
207d0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
207e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
207f0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
20800 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 TRIGGER 7
20810 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
20820 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
20830 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
20840 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 SQLITE_CREATE_V
20850 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 IEW 8
20860 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
20870 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
20880 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
20890 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 SQLITE_DELETE
208a0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 9
208b0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
208c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
208d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
208e0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 QLITE_DROP_INDEX
208f0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 10
20900 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
20910 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
20920 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20930 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 LITE_DROP_TABLE
20940 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 11 /
20950 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
20960 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
20970 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
20980 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e ITE_DROP_TEMP_IN
20990 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a DEX 12 /*
209a0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
209b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
209c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
209d0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 TE_DROP_TEMP_TAB
209e0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 LE 13 /*
209f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
20a00 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
20a10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20a20 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 E_DROP_TEMP_TRIG
20a30 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 GER 14 /* T
20a40 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
20a50 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
20a60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
20a70 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 _DROP_TEMP_VIEW
20a80 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 15 /* Vi
20a90 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
20aa0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
20ab0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20ac0 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 DROP_TRIGGER
20ad0 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 16 /* Tri
20ae0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
20af0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
20b00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
20b10 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 ROP_VIEW
20b20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 17 /* View
20b30 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
20b40 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
20b50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
20b60 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 SERT
20b70 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 18 /* Table
20b80 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
20b90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
20ba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 efine SQLITE_PRA
20bb0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 GMA
20bc0 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 19 /* Pragma
20bd0 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 Name 1st ar
20be0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 g or NULL */.#de
20bf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
20c00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20c10 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 20 /* Table N
20c20 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 ame Column
20c30 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
20c40 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 ine SQLITE_SELEC
20c50 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
20c60 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 21 /* NULL
20c70 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 NULL
20c80 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
20c90 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 ne SQLITE_TRANSA
20ca0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 CTION 2
20cb0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 2 /* Operation
20cc0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
20cd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
20ce0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 e SQLITE_UPDATE
20cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 23
20d00 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
20d10 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d Column Nam
20d20 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
20d30 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 SQLITE_ATTACH
20d40 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 24
20d50 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 /* Filename
20d60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
20d70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
20d80 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 SQLITE_DETACH
20d90 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 25
20da0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d /* Database Nam
20db0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 e NULL
20dc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
20dd0 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c QLITE_ALTER_TABL
20de0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 E 26
20df0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 /* Database Name
20e00 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
20e10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20e20 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 LITE_REINDEX
20e30 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 27 /
20e40 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
20e50 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
20e60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
20e70 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 ITE_ANALYZE
20e80 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 28 /*
20e90 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
20ea0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
20eb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20ec0 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 TE_CREATE_VTABLE
20ed0 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 29 /*
20ee0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
20ef0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 Module Name
20f00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20f10 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 E_DROP_VTABLE
20f20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 30 /* T
20f30 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d able Name M
20f40 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a odule Name *
20f50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
20f60 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 _FUNCTION
20f70 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 31 /* NU
20f80 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 LL Fu
20f90 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f nction Name */
20fa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20fb0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 SAVEPOINT
20fc0 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 32 /* Ope
20fd0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 ration Sav
20fe0 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a epoint Name */.
20ff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
21000 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 OPY
21010 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 0 /* No l
21020 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 onger used */.#d
21030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 efine SQLITE_REC
21040 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 URSIVE
21050 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 33 /* NULL
21060 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 NULL
21070 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a */../*
21080 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 .** CAPI3REF: Tr
21090 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c acing And Profil
210a0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a ing Functions.**
210b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
210c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
210d0 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 tines register c
210e0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
210f0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 s that can be us
21100 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e ed for.** tracin
21110 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 g and profiling
21120 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 the execution of
21130 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e SQL statements.
21140 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c .**.** ^The call
21150 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 back function re
21160 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 gistered by sqli
21170 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 te3_trace() is i
21180 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 nvoked at.** var
21190 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 ious times when
211a0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
211b0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 is being run by
211c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
211d0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 ]..** ^The sqlit
211e0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 e3_trace() callb
211f0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
21200 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 ith a UTF-8 rend
21210 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 ering of the.**
21220 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 SQL statement te
21230 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d xt as the statem
21240 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 ent first begins
21250 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e executing..** ^
21260 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 (Additional sqli
21270 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c te3_trace() call
21280 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 backs might occu
21290 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 r.** as each tri
212a0 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 ggered subprogra
212b0 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 m is entered. T
212c0 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 he callbacks for
212d0 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e triggers.** con
212e0 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c tain a UTF-8 SQL
212f0 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 comment that id
21300 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 entifies the tri
21310 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 gger.)^.**.** Th
21320 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f e [SQLITE_TRACE_
21330 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 SIZE_LIMIT] comp
21340 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
21350 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c can be used to l
21360 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 imit.** the leng
21370 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 th of [bound par
21380 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f ameter] expansio
21390 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 n in the output
213a0 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 of sqlite3_trace
213b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 ()..**.** ^The c
213c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
213d0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 registered by s
213e0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 qlite3_profile()
213f0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 is invoked.** a
21400 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 s each SQL state
21410 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 ment finishes.
21420 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c ^The profile cal
21430 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a lback contains.*
21440 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 * the original s
21450 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e tatement text an
21460 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 d an estimate of
21470 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 wall-clock time
21480 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 .** of how long
21490 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 that statement t
214a0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 ook to run. ^Th
214b0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 e profile callba
214c0 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e ck.** time is in
214d0 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 units of nanose
214e0 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 conds, however t
214f0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 he current imple
21500 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 mentation.** is
21510 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 only capable of
21520 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f millisecond reso
21530 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 lution so the si
21540 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 x least signific
21550 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e ant.** digits in
21560 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 the time are me
21570 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 aningless. Futu
21580 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
21590 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 QLite.** might p
215a0 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 rovide greater r
215b0 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 esolution on the
215c0 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 profiler callba
215d0 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 ck. The.** sqli
215e0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 te3_profile() fu
215f0 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 nction is consid
21600 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 ered experimenta
21610 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a l and is.** subj
21620 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e ect to change in
21630 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 future versions
21640 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 of SQLite..*/.S
21650 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
21660 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
21670 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c qlite3_trace(sql
21680 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 ite3*, void(*xTr
21690 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ace)(void*,const
216a0 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b char*), void*);
216b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
216c0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
216d0 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 void *SQLITE_STD
216e0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f CALL sqlite3_pro
216f0 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 file(sqlite3*,.
21700 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 void(*xProfile
21710 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 )(void*,const ch
21720 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 ar*,sqlite3_uint
21730 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 64), void*);../*
21740 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 .** CAPI3REF: Qu
21750 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c ery Progress Cal
21760 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 lbacks.** METHOD
21770 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
21780 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f ^The sqlite3_pro
21790 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c gress_handler(D,
217a0 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 N,X,P) interface
217b0 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c causes the call
217c0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
217d0 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 X to be invoked
217e0 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 periodically du
217f0 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e ring long runnin
21800 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 g calls to.** [s
21810 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 qlite3_exec()],
21820 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
21830 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 and [sqlite3_ge
21840 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a t_table()] for.*
21850 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
21860 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 ction D. An exa
21870 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 mple use for thi
21880 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 s.** interface i
21890 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 s to keep a GUI
218a0 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 updated during a
218b0 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a large query..**
218c0 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 .** ^The paramet
218d0 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 er P is passed t
218e0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e hrough as the on
218f0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ly parameter to
21900 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b the .** callback
21910 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 function X. ^T
21920 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 he parameter N i
21930 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 s the approximat
21940 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 e number of .**
21950 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 [virtual machine
21960 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 instructions] t
21970 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 hat are evaluate
21980 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 d between succes
21990 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 sive.** invocati
219a0 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 ons of the callb
219b0 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 ack X. ^If N is
219c0 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 less than one t
219d0 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 hen the progress
219e0 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 .** handler is d
219f0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e isabled..**.** ^
21a00 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 Only a single pr
21a10 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d ogress handler m
21a20 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 ay be defined at
21a30 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a one time per.**
21a40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
21a50 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 ction]; setting
21a60 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 a new progress h
21a70 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 andler cancels t
21a80 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 he.** old one.
21a90 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 ^Setting paramet
21aa0 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 er X to NULL dis
21ab0 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 ables the progre
21ac0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e ss handler..** ^
21ad0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e The progress han
21ae0 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 dler is also dis
21af0 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 abled by setting
21b00 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 N to a value le
21b10 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a ss.** than 1..**
21b20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 .** ^If the prog
21b30 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 ress callback re
21b40 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
21b50 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 the operation is
21b60 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e .** interrupted.
21b70 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 This feature c
21b80 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d an be used to im
21b90 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 plement a.** "Ca
21ba0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 ncel" button on
21bb0 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 a GUI progress d
21bc0 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a ialog box..**.**
21bd0 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 The progress ha
21be0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d ndler callback m
21bf0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 ust not do anyth
21c00 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f ing that will mo
21c10 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 dify.** the data
21c20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
21c30 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
21c40 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
21c50 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 r..** Note that
21c60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
21c70 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 _v2()] and [sqli
21c80 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 te3_step()] both
21c90 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a modify their.**
21ca0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
21cb0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 tions for the me
21cc0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 aning of "modify
21cd0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 " in this paragr
21ce0 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 aph..**.*/.SQLIT
21cf0 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 E_API void SQLIT
21d00 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
21d10 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 3_progress_handl
21d20 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 er(sqlite3*, int
21d30 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c , int(*)(void*),
21d40 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
21d50 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e CAPI3REF: Openin
21d60 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 g A New Database
21d70 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 Connection.** C
21d80 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 ONSTRUCTOR: sqli
21d90 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 te3.**.** ^These
21da0 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 routines open a
21db0 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 n SQLite databas
21dc0 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 e file as specif
21dd0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 ied by the .** f
21de0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
21df0 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 . ^The filename
21e00 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 argument is inte
21e10 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 rpreted as UTF-8
21e20 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
21e30 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
21e40 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 e3_open_v2() and
21e50 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 as UTF-16 in th
21e60 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a e native byte.**
21e70 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 order for sqlit
21e80 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 e3_open16(). ^(A
21e90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
21ea0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 ction] handle is
21eb0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 usually.** retu
21ec0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 rned in *ppDb, e
21ed0 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 ven if an error
21ee0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c occurs. The onl
21ef0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 y exception is t
21f00 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 hat.** if SQLite
21f10 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c is unable to al
21f20 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f locate memory to
21f30 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 hold the [sqlit
21f40 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 e3] object,.** a
21f50 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 NULL will be wr
21f60 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 itten into *ppDb
21f70 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f instead of a po
21f80 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 inter to the [sq
21f90 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 lite3].** object
21fa0 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 .)^ ^(If the dat
21fb0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
21fc0 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 (and/or created)
21fd0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 successfully, t
21fe0 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f hen.** [SQLITE_O
21ff0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 K] is returned.
22000 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 Otherwise an [e
22010 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
22020 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a turned.)^ ^The.*
22030 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 * [sqlite3_errms
22040 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 g()] or [sqlite3
22050 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 _errmsg16()] rou
22060 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 tines can be use
22070 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 d to obtain.** a
22080 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 n English langua
22090 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f ge description o
220a0 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c f the error foll
220b0 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 owing a failure
220c0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 of any.** of the
220d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
220e0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
220f0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 ^The default enc
22100 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 oding will be UT
22110 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 F-8 for database
22120 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a s created using.
22130 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ** sqlite3_open(
22140 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 ) or sqlite3_ope
22150 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 n_v2(). ^The de
22160 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 fault encoding f
22170 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 or databases.**
22180 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 created using sq
22190 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 lite3_open16() w
221a0 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e ill be UTF-16 in
221b0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
221c0 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 order..**.** Wh
221d0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 ether or not an
221e0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 error occurs whe
221f0 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 n it is opened,
22200 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 resources.** ass
22210 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
22220 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
22230 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 ction] handle sh
22240 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 ould be released
22250 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 by.** passing i
22260 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c t to [sqlite3_cl
22270 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 ose()] when it i
22280 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 s no longer requ
22290 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ired..**.** The
222a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
222b0 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b ) interface work
222c0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f s like sqlite3_o
222d0 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 pen().** except
222e0 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 that it accepts
222f0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 two additional p
22300 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 arameters for ad
22310 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c ditional control
22320 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 .** over the new
22330 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
22340 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 tion. ^(The fla
22350 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a gs parameter to.
22360 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f ** sqlite3_open_
22370 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e v2() can take on
22380 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c e of.** the foll
22390 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 owing three valu
223a0 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 es, optionally c
223b0 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 ombined with the
223c0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 .** [SQLITE_OPE
223d0 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c N_NOMUTEX], [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 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 EX], [SQLITE_OPE
22400 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a N_SHAREDCACHE],.
22410 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
22420 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 PRIVATECACHE], a
22430 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 nd/or [SQLITE_OP
22440 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e EN_URI] flags:)^
22450 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e .**.** <dl>.** ^
22460 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 (<dt>[SQLITE_OPE
22470 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e N_READONLY]</dt>
22480 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
22490 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 base is opened i
224a0 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 n read-only mode
224b0 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 . If the databa
224c0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 se does not.** a
224d0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e lready exist, an
224e0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
224f0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a ed.</dd>)^.**.**
22500 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ^(<dt>[SQLITE_O
22510 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f PEN_READWRITE]</
22520 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
22530 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
22540 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e d for reading an
22550 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 d writing if pos
22560 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e sible, or readin
22570 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 g.** only if the
22580 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 file is write p
22590 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 rotected by the
225a0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
225b0 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 . In either.**
225c0 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 case the databas
225d0 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 e must already e
225e0 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 xist, otherwise
225f0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 an error is retu
22600 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a rned.</dd>)^.**.
22610 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 ** ^(<dt>[SQLITE
22620 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d _OPEN_READWRITE]
22630 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f | [SQLITE_OPEN_
22640 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 CREATE]</dt>.**
22650 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 <dd>The database
22660 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
22670 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 eading and writi
22680 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 ng, and is creat
22690 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 ed if.** it does
226a0 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 not already exi
226b0 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 st. This is the
226c0 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 behavior that is
226d0 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 always used for
226e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
226f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
22700 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a pen16().</dd>)^.
22710 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </dl>.**.** I
22720 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 f the 3rd parame
22730 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ter to sqlite3_o
22740 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 pen_v2() is not
22750 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f one of the.** co
22760 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e mbinations shown
22770 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c above optionall
22780 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 y combined with
22790 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 other.** [SQLITE
227a0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c _OPEN_READONLY |
227b0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 SQLITE_OPEN_* b
227c0 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 its].** then the
227d0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
227e0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 efined..**.** ^I
227f0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 f the [SQLITE_OP
22800 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 EN_NOMUTEX] flag
22810 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 is set, then th
22820 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
22830 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 ction.** opens i
22840 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 n the multi-thre
22850 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ad [threading mo
22860 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 de] as long as t
22870 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 he single-thread
22880 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 .** mode has not
22890 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d been set at com
228a0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 pile-time or sta
228b0 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 rt-time. ^If th
228c0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 e.** [SQLITE_OPE
228d0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 N_FULLMUTEX] fla
228e0 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 g is set then th
228f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
22900 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 ction opens.** i
22910 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 n the serialized
22920 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
22930 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d ] unless single-
22940 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 thread was.** pr
22950 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 eviously selecte
22960 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d d at compile-tim
22970 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e e or start-time.
22980 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
22990 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
229a0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 E] flag causes t
229b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
229c0 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 ection to be.**
229d0 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 eligible to use
229e0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f [shared cache mo
229f0 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 de], regardless
22a00 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
22a10 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 t shared.** cach
22a20 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 e is enabled usi
22a30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 ng [sqlite3_enab
22a40 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 le_shared_cache(
22a50 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 )]. ^The.** [SQ
22a60 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 LITE_OPEN_PRIVAT
22a70 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 ECACHE] flag cau
22a80 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ses the database
22a90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e connection to n
22aa0 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 ot.** participat
22ab0 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 e in [shared cac
22ac0 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 he mode] even if
22ad0 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a it is enabled..
22ae0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 **.** ^The fourt
22af0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
22b00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
22b10 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
22b20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
22b30 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 vfs] object that
22b40 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 defines the ope
22b50 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e rating system in
22b60 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 terface that.**
22b70 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 the new database
22b80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 connection shou
22b90 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 ld use. ^If the
22ba0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
22bb0 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 r is.** a NULL p
22bc0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 ointer then the
22bd0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
22be0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 _vfs] object is
22bf0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 used..**.** ^If
22c00 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
22c10 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e ":memory:", then
22c20 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 a private, temp
22c30 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 orary in-memory
22c40 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 database.** is c
22c50 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 reated for the c
22c60 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 onnection. ^Thi
22c70 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 s in-memory data
22c80 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 base will vanish
22c90 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 when.** the dat
22ca0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
22cb0 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 is closed. Fut
22cc0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
22cd0 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 SQLite might.**
22ce0 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 make use of addi
22cf0 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 tional special f
22d00 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 ilenames that be
22d10 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 gin with the ":"
22d20 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 character..** I
22d30 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 t is recommended
22d40 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 that when a dat
22d50 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 abase filename a
22d60 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 ctually does beg
22d70 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 in with.** a ":"
22d80 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 character you s
22d90 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 hould prefix the
22da0 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 filename with a
22db0 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 pathname such a
22dc0 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f s.** "./" to avo
22dd0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a id ambiguity..**
22de0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 .** ^If the file
22df0 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 name is an empty
22e00 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 string, then a
22e10 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 private, tempora
22e20 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 ry.** on-disk da
22e30 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 tabase will be c
22e40 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 reated. ^This p
22e50 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 rivate database
22e60 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d will be.** autom
22e70 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 atically deleted
22e80 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 as soon as the
22e90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
22ea0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a ion is closed..*
22eb0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e *.** [[URI filen
22ec0 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f ames in sqlite3_
22ed0 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 open()]] <h3>URI
22ee0 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a Filenames</h3>.
22ef0 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 **.** ^If [URI f
22f00 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 ilename] interpr
22f10 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c etation is enabl
22f20 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 ed, and the file
22f30 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a name argument.**
22f40 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 begins with "fi
22f50 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 le:", then the f
22f60 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 ilename is inter
22f70 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e preted as a URI.
22f80 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d ^URI.** filenam
22f90 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e e interpretation
22fa0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 is enabled if t
22fb0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
22fc0 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 URI] flag is.**
22fd0 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 set in the fourt
22fe0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 h argument to sq
22ff0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c lite3_open_v2(),
23000 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a or if it has.**
23010 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c been enabled gl
23020 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 obally using the
23030 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
23040 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 URI] option with
23050 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
23060 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f _config()] metho
23070 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c d or by the [SQL
23080 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d ITE_USE_URI] com
23090 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
230a0 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 ..** As of SQLit
230b0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c e version 3.7.7,
230c0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e URI filename in
230d0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 terpretation is
230e0 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 turned off.** by
230f0 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 default, but fu
23100 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
23110 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e SQLite might en
23120 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d able URI filenam
23130 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 e.** interpretat
23140 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 ion by default.
23150 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e See "[URI filen
23160 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 ames]" for addit
23170 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 ional.** informa
23180 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 tion..**.** URI
23190 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 filenames are pa
231a0 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 rsed according t
231b0 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 o RFC 3986. ^If
231c0 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 the URI contains
231d0 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 an.** authority
231e0 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 , then it must b
231f0 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 e either an empt
23200 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 y string or the
23210 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 string .** "loca
23220 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 lhost". ^If the
23230 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 authority is not
23240 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
23250 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c or "localhost",
23260 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 an .** error is
23270 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 returned to the
23280 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 caller. ^The fr
23290 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 agment component
232a0 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a of a URI, if .*
232b0 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 * present, is ig
232c0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 nored..**.** ^SQ
232d0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 Lite uses the pa
232e0 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 th component of
232f0 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e the URI as the n
23300 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 ame of the disk
23310 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f file.** which co
23320 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 ntains the datab
23330 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 ase. ^If the pat
23340 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 h begins with a
23350 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a '/' character, .
23360 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e ** then it is in
23370 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 terpreted as an
23380 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e absolute path. ^
23390 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 If the path does
233a0 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 not begin .** w
233b0 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 ith a '/' (meani
233c0 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 ng that the auth
233d0 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 ority section is
233e0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 omitted from th
233f0 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 e URI).** then t
23400 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 he path is inter
23410 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 preted as a rela
23420 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e tive path. .** ^
23430 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 (On windows, the
23440 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 first component
23450 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 of an absolute
23460 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 path .** is a dr
23470 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f ive specificatio
23480 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e n (e.g. "C:").)^
23490 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 .**.** [[core UR
234a0 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 I query paramete
234b0 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 rs]].** The quer
234c0 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 y component of a
234d0 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e URI may contain
234e0 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 parameters that
234f0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
23500 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 .** either by SQ
23510 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 Lite itself, or
23520 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 by a [VFS | cust
23530 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 om VFS implement
23540 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 ation]..** SQLit
23550 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d e and its built-
23560 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 in [VFSes] inter
23570 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c pret the.** foll
23580 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 owing query para
23590 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 meters:.**.** <u
235a0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e l>.** <li> <b>
235b0 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 vfs</b>: ^The "v
235c0 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 fs" parameter ma
235d0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 y be used to spe
235e0 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 cify the name of
235f0 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 .** a VFS ob
23600 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 ject that provid
23610 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 es the operating
23620 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 system interfac
23630 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a e that should.**
23640 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 be used to
23650 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 access the datab
23660 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b ase file on disk
23670 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f . ^If this optio
23680 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 n is set to.**
23690 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 an empty stri
236a0 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 ng the default V
236b0 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 FS object is use
236c0 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 d. ^Specifying a
236d0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 n unknown.**
236e0 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 VFS is an error
236f0 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 . ^If sqlite3_op
23700 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 en_v2() is used
23710 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 and the vfs opti
23720 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 on is.** pre
23730 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 sent, then the V
23740 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 FS specified by
23750 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 the option takes
23760 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 precedence over
23770 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 .** the valu
23780 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
23790 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
237a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
237b0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c _v2()..**.** <
237c0 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a li> <b>mode</b>:
237d0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 ^(The mode para
237e0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 meter may be set
237f0 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c to either "ro",
23800 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 "rw",.** "r
23810 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 wc", or "memory"
23820 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 . Attempting to
23830 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 set it to any ot
23840 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 her value is.**
23850 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 an error)^.
23860 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 .** ^If "ro"
23870 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 is specified, t
23880 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
23890 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
238a0 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 ead-only .**
238b0 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 access, just as
238c0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f if the [SQLITE_
238d0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 OPEN_READONLY] f
238e0 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 lag had been set
238f0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 in the .**
23900 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 third argument t
23910 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
23920 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 2(). ^If the mod
23930 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 e option is set
23940 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c to .** "rw",
23950 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
23960 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
23970 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 read-write (but
23980 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a not create) .**
23990 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 access, as
239a0 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 if SQLITE_OPEN_R
239b0 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f EADWRITE (but no
239c0 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 t SQLITE_OPEN_CR
239d0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 EATE) had .**
239e0 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c been set. ^Val
239f0 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 ue "rwc" is equi
23a00 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e valent to settin
23a10 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 g both .** S
23a20 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
23a30 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f RITE and SQLITE_
23a40 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 OPEN_CREATE. ^I
23a50 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f f the mode optio
23a60 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 n is.** set
23a70 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e to "memory" then
23a80 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f a pure [in-memo
23a90 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 ry database] tha
23aa0 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a t never reads.**
23ab0 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 or writes f
23ac0 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 rom disk is used
23ad0 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f . ^It is an erro
23ae0 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 r to specify a v
23af0 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 alue for.**
23b00 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 the mode paramet
23b10 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 er that is less
23b20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e restrictive than
23b30 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 that specified
23b40 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c by.** the fl
23b50 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 ags passed in th
23b60 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
23b70 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
23b80 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 n_v2()..**.**
23b90 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 <li> <b>cache</b
23ba0 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 >: ^The cache pa
23bb0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 rameter may be s
23bc0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 et to either "sh
23bd0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 ared" or.**
23be0 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 "private". ^Sett
23bf0 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 ing it to "share
23c00 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 d" is equivalent
23c10 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a to setting the.
23c20 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 ** SQLITE_OP
23c30 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 EN_SHAREDCACHE b
23c40 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 it in the flags
23c50 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 argument passed
23c60 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 to.** sqlite
23c70 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 3_open_v2(). ^Se
23c80 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 tting the cache
23c90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 parameter to "pr
23ca0 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 ivate" is .**
23cb0 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 equivalent to
23cc0 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 setting the SQLI
23cd0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
23ce0 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 ACHE bit..**
23cf0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 ^If sqlite3_ope
23d00 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 n_v2() is used a
23d10 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 nd the "cache" p
23d20 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 arameter is pres
23d30 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 ent in.** a
23d40 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 URI filename, it
23d50 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 s value override
23d60 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 s any behavior r
23d70 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 equested by sett
23d80 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 ing.** SQLIT
23d90 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
23da0 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 CHE or SQLITE_OP
23db0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 EN_SHAREDCACHE f
23dc0 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e lag..**.** <li>
23dd0 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 <b>psow</b>: ^T
23de0 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 he psow paramete
23df0 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 r indicates whet
23e00 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a her or not the.*
23e10 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 * [powersafe
23e20 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 overwrite] prop
23e30 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 erty does or doe
23e40 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 s not apply to t
23e50 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 he.** storag
23e60 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 e media on which
23e70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
23e80 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a le resides..**.*
23e90 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 * <li> <b>noloc
23ea0 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f k</b>: ^The nolo
23eb0 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 ck parameter is
23ec0 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 a boolean query
23ed0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 parameter.**
23ee0 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 which if set di
23ef0 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b sables file lock
23f00 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 ing in rollback
23f10 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 journal modes.
23f20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 This.** is u
23f30 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 seful for access
23f40 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f ing a database o
23f50 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 n a filesystem t
23f60 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 hat does not.**
23f70 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b support lock
23f80 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 ing. Caution:
23f90 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 Database corrupt
23fa0 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 ion might result
23fb0 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f if two.** o
23fc0 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 r more processes
23fd0 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 write to the sa
23fe0 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 me database and
23ff0 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 any one of those
24000 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 .** processe
24010 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e s uses nolock=1.
24020 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e .**.** <li> <b>
24030 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e immutable</b>: ^
24040 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 The immutable pa
24050 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f rameter is a boo
24060 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 lean query.**
24070 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 parameter that
24080 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 indicates that
24090 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
240a0 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a e is stored on.*
240b0 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 * read-only
240c0 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d media. ^When im
240d0 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 mutable is set,
240e0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 SQLite assumes t
240f0 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 hat the.** d
24100 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e atabase file can
24110 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 not be changed,
24120 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 even by a proces
24130 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a s with higher.**
24140 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 privilege,
24150 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 and so the datab
24160 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 ase is opened re
24170 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 ad-only and all
24180 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 locking.** a
24190 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 nd change detect
241a0 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e ion is disabled.
241b0 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 Caution: Setti
241c0 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 ng the immutable
241d0 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 .** property
241e0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 on a database f
241f0 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e ile that does in
24200 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e fact change can
24210 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 result.** i
24220 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 n incorrect quer
24230 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 y results and/or
24240 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 [SQLITE_CORRUPT
24250 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 ] errors..**
24260 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 See also: [SQLI
24270 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 TE_IOCAP_IMMUTAB
24280 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a LE]..** .*
24290 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 * </ul>.**.** ^S
242a0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b pecifying an unk
242b0 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 nown parameter i
242c0 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 n the query comp
242d0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 onent of a URI i
242e0 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f s not an.** erro
242f0 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 r. Future versi
24300 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 ons of SQLite mi
24310 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 ght understand a
24320 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a dditional query.
24330 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ** parameters.
24340 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 See "[query para
24350 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 meters with spec
24360 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 ial meaning to S
24370 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 QLite]" for.** a
24380 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
24390 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 ation..**.** [[U
243a0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d RI filename exam
243b0 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 ples]] <h3>URI f
243c0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 ilename examples
243d0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 </h3>.**.** <tab
243e0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c le border="1" al
243f0 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 ign=center cellp
24400 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 adding=5>.** <tr
24410 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 ><th> URI filena
24420 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 mes <th> Results
24430 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
24440 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a e:data.db <td> .
24450 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e ** Open
24460 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e the file "data.
24470 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 db" in the curre
24480 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a nt directory..**
24490 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f <tr><td> file:/
244a0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
244b0 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 b<br>.**
244c0 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 file:///home/f
244d0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e red/data.db <br>
244e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 .** fi
244f0 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 le://localhost/h
24500 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
24510 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 <br> <td> .**
24520 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 Open the
24530 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 database file "
24540 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
24550 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e db"..** <tr><td>
24560 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 file://darkstar
24570 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
24580 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 db <td> .**
24590 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 An error. "
245a0 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 darkstar" is not
245b0 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 a recognized au
245c0 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e thority..** <tr>
245d0 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 <td style="white
245e0 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 -space:nowrap">
245f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c .** fil
24600 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 e:///C:/Document
24610 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e s%20and%20Settin
24620 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f gs/fred/Desktop/
24630 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c data.db.** <
24640 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 td> Windows only
24650 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 : Open the file
24660 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 "data.db" on fre
24670 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 d's desktop on d
24680 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 rive.**
24690 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 C:. Note that t
246a0 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 he %20 escaping
246b0 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 in this example
246c0 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 is not strictly
246d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 .** nec
246e0 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 essary - space c
246f0 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 haracters can be
24700 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a used literally.
24710 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 ** in U
24720 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a RI filenames..**
24730 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 <tr><td> file:d
24740 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 ata.db?mode=ro&c
24750 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 ache=private <td
24760 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f > .** O
24770 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 pen file "data.d
24780 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e b" in the curren
24790 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 t directory for
247a0 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 read-only access
247b0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 ..** Re
247c0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
247d0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 her or not share
247e0 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 d-cache mode is
247f0 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 enabled by.**
24800 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 default,
24810 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 use a private ca
24820 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e che..** <tr><td>
24830 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 file:/home/fred
24840 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 /data.db?vfs=uni
24850 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a x-dotfile <td>.*
24860 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 * Open
24870 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 file "/home/fred
24880 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 /data.db". Use t
24890 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 he special VFS "
248a0 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a unix-dotfile".**
248b0 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 that u
248c0 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e ses dot-files in
248d0 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 place of posix
248e0 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 advisory locking
248f0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 ..** <tr><td> fi
24900 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d le:data.db?mode=
24910 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a readonly <td> .*
24920 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 * An er
24930 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 ror. "readonly"
24940 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f is not a valid o
24950 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d ption for the "m
24960 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a ode" parameter..
24970 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a ** </table>.**.*
24980 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d * ^URI hexadecim
24990 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e al escape sequen
249a0 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 ces (%HH) are su
249b0 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 pported within t
249c0 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 he path and.** q
249d0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 uery components
249e0 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 of a URI. A hexa
249f0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 decimal escape s
24a00 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 equence consists
24a10 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 of a.** percent
24a20 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f sign - "%" - fo
24a30 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c llowed by exactl
24a40 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 y two hexadecima
24a50 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 l digits .** spe
24a60 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 cifying an octet
24a70 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 value. ^Before
24a80 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 the path or quer
24a90 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 y components of
24aa0 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d a.** URI filenam
24ab0 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 e are interprete
24ac0 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f d, they are enco
24ad0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 ded using UTF-8
24ae0 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 and all .** hexa
24af0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 decimal escape s
24b00 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 equences replace
24b10 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 d by a single by
24b20 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 te containing th
24b30 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 e.** correspondi
24b40 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 ng octet. If thi
24b50 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 s process genera
24b60 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 tes an invalid U
24b70 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a TF-8 encoding,.*
24b80 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 * the results ar
24b90 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a e undefined..**.
24ba0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 ** <b>Note to Wi
24bb0 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e ndows users:</b>
24bc0 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 The encoding u
24bd0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 sed for the file
24be0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a name argument.**
24bf0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e of sqlite3_open
24c00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
24c10 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 pen_v2() must be
24c20 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 UTF-8, not what
24c30 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 ever.** codepage
24c40 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 is currently de
24c50 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 fined. Filename
24c60 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 s containing int
24c70 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 ernational.** ch
24c80 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 aracters must be
24c90 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 converted to UT
24ca0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 F-8 prior to pas
24cb0 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a sing them into.*
24cc0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
24cd0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e or sqlite3_open
24ce0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e _v2()..**.** <b>
24cf0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 Note to Windows
24d00 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f Runtime users:</
24d10 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 b> The temporar
24d20 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 y directory must
24d30 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 be set.** prior
24d40 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 to calling sqli
24d50 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 te3_open() or sq
24d60 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
24d70 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 Otherwise, var
24d80 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 ious.** features
24d90 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 that require th
24da0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 e use of tempora
24db0 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 ry files may fai
24dc0 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 l..**.** See als
24dd0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 o: [sqlite3_temp
24de0 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 _directory].*/.S
24df0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
24e00 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
24e10 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e ite3_open(. con
24e20 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d st char *filenam
24e30 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 e, /* Database
24e40 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 filename (UTF-8
24e50 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a ) */. sqlite3 *
24e60 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f *ppDb /
24e70 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 * OUT: SQLite db
24e80 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 handle */.);.SQ
24e90 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
24ea0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
24eb0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f te3_open16(. co
24ec0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 nst void *filena
24ed0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
24ee0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
24ef0 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 16) */. sqlite3
24f00 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
24f10 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
24f20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
24f30 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
24f40 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
24f50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 lite3_open_v2(.
24f60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c const char *fil
24f70 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
24f80 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
24f90 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 TF-8) */. sqlit
24fa0 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 e3 **ppDb,
24fb0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
24fc0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 e db handle */.
24fd0 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 int flags,
24fe0 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 /* Flag
24ff0 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 s */. const cha
25000 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f r *zVfs /
25010 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f * Name of VFS mo
25020 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 dule to use */.)
25030 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
25040 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 F: Obtain Values
25050 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 For URI Paramet
25060 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ers.**.** These
25070 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 are utility rout
25080 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 ines, useful to
25090 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
250a0 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a ons, that check.
250b0 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 ** to see if a d
250c0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 atabase file was
250d0 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 a URI that cont
250e0 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 ained a specific
250f0 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d query .** param
25100 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 eter, and if so
25110 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 obtains the valu
25120 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 e of that query
25130 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
25140 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 If F is the dat
25150 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 abase filename p
25160 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e ointer passed in
25170 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d to the xOpen() m
25180 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 ethod of .** a V
25190 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
251a0 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 n when the flags
251b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
251c0 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 pen() has one or
251d0 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 .** more of the
251e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 [SQLITE_OPEN_UR
251f0 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 I] or [SQLITE_OP
25200 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 EN_MAIN_DB] bits
25210 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 set and.** P is
25220 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
25230 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
25240 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 , then.** sqlite
25250 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
25260 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 F,P) returns the
25270 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a value of the P.
25280 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 ** parameter if
25290 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e it exists or a N
252a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 ULL pointer if P
252b0 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 does not appear
252c0 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 as a .** query
252d0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 parameter on F.
252e0 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 If P is a query
252f0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a parameter of F.
25300 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 ** has no explic
25310 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 it value, then s
25320 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d qlite3_uri_param
25330 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e eter(F,P) return
25340 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 s.** a pointer t
25350 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e o an empty strin
25360 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c g..**.** The sql
25370 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e ite3_uri_boolean
25380 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 (F,P,B) routine
25390 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 assumes that P i
253a0 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 s a boolean.** p
253b0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 arameter and ret
253c0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 urns true (1) or
253d0 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 false (0) accor
253e0 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 ding to the valu
253f0 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 e.** of P. The
25400 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c sqlite3_uri_bool
25410 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 ean(F,P,B) routi
25420 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 ne returns true
25430 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 (1) if the.** va
25440 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 lue of query par
25450 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 ameter P is one
25460 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 of "yes", "true"
25470 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 , or "on" in any
25480 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 .** case or if t
25490 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 he value begins
254a0 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 with a non-zero
254b0 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a number. The .**
254c0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
254d0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 lean(F,P,B) rout
254e0 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c ines returns fal
254f0 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 se (0) if the va
25500 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 lue of.** query
25510 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f parameter P is o
25520 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c ne of "no", "fal
25530 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e se", or "off" in
25540 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 any case or.**
25550 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 if the value beg
25560 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 ins with a numer
25570 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 ic zero. If P i
25580 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a s not a query.**
25590 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 parameter on F
255a0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 or if the value
255b0 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 of P is does not
255c0 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 match any of th
255d0 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e e.** above, then
255e0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
255f0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 lean(F,P,B) retu
25600 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a rns (B!=0)..**.*
25610 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 * The sqlite3_ur
25620 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 i_int64(F,P,D) r
25630 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 outine converts
25640 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 the value of P i
25650 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 nto a.** 64-bit
25660 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 signed integer a
25670 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 nd returns that
25680 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 integer, or D if
25690 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 P does not.** e
256a0 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 xist. If the va
256b0 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 lue of P is some
256c0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e thing other than
256d0 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 an integer, the
256e0 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 n.** zero is ret
256f0 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 urned..** .** If
25700 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 F is a NULL poi
25710 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 nter, then sqlit
25720 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 e3_uri_parameter
25730 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 (F,P) returns NU
25740 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 LL and.** sqlite
25750 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 3_uri_boolean(F,
25760 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 P,B) returns B.
25770 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e If F is not a N
25780 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a ULL pointer and.
25790 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 ** is not a data
257a0 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 base file pathna
257b0 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 me pointer that
257c0 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e SQLite passed in
257d0 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 to the xOpen.**
257e0 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e VFS method, then
257f0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
25800 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
25810 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 undefined and p
25820 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 robably.** undes
25830 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 irable..*/.SQLIT
25840 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
25850 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
25860 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 sqlite3_uri_par
25870 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 ameter(const cha
25880 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f r *zFilename, co
25890 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d nst char *zParam
258a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
258b0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
258c0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
258d0 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 lean(const char
258e0 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 *zFile, const ch
258f0 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 ar *zParam, int
25900 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 bDefault);.SQLIT
25910 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e E_API sqlite3_in
25920 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 t64 SQLITE_STDCA
25930 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 LL sqlite3_uri_i
25940 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a nt64(const char*
25950 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 , const char*, s
25960 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a qlite3_int64);..
25970 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
25980 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 Error Codes And
25990 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 Messages.** MET
259a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
259b0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
259c0 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a recent sqlite3_*
259d0 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 API call associ
259e0 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 ated with .** [d
259f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
25a00 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 on] D failed, th
25a10 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 en the sqlite3_e
25a20 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 rrcode(D) interf
25a30 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 ace.** returns t
25a40 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 he numeric [resu
25a50 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 lt code] or [ext
25a60 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
25a70 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 e] for that.** A
25a80 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 PI call..** If t
25a90 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 he most recent A
25aa0 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 PI call was succ
25ab0 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 essful,.** then
25ac0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
25ad0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 from sqlite3_er
25ae0 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 rcode() is undef
25af0 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 ined..** ^The sq
25b00 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
25b10 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 rrcode().** inte
25b20 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d rface is the sam
25b30 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 e except that it
25b40 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
25b50 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 the .** [extende
25b60 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 d result code] e
25b70 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 ven when extende
25b80 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
25b90 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a re.** disabled..
25ba0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
25bb0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 e3_errmsg() and
25bc0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
25bd0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 () return Englis
25be0 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 h-language.** te
25bf0 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 xt that describe
25c00 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 s the error, as
25c10 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
25c20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 UTF-16 respectiv
25c30 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 ely..** ^(Memory
25c40 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 to hold the err
25c50 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
25c60 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 g is managed int
25c70 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 ernally..** The
25c80 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 application does
25c90 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 not need to wor
25ca0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 ry about freeing
25cb0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 the result..**
25cc0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 However, the err
25cd0 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 or string might
25ce0 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f be overwritten o
25cf0 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 r deallocated by
25d00 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 .** subsequent c
25d10 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 alls to other SQ
25d20 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 Lite interface f
25d30 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a unctions.)^.**.*
25d40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
25d50 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 rrstr() interfac
25d60 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e e returns the En
25d70 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 glish-language t
25d80 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 ext.** that desc
25d90 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c ribes the [resul
25da0 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d t code], as UTF-
25db0 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 8..** ^(Memory t
25dc0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 o hold the error
25dd0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
25de0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 is managed inter
25df0 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 nally.** and mus
25e00 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 t not be freed b
25e10 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
25e20 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 n)^..**.** When
25e30 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b the serialized [
25e40 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
25e50 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 is in use, it mi
25e60 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 ght be the.** ca
25e70 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 se that a second
25e80 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e error occurs on
25e90 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
25ea0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a ad in between.**
25eb0 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 the time of the
25ec0 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 first error and
25ed0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 the call to the
25ee0 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a se interfaces..*
25ef0 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 * When that happ
25f00 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 ens, the second
25f10 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
25f20 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 ported since the
25f30 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 se.** interfaces
25f40 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 always report t
25f50 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 he most recent r
25f60 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 esult. To avoid
25f70 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 .** this, each t
25f80 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e hread can obtain
25f90 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f exclusive use o
25fa0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
25fb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a connection] D.**
25fc0 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 by invoking [sq
25fd0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
25fe0 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d r]([sqlite3_db_m
25ff0 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 utex](D)) before
26000 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f beginning.** to
26010 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b use D and invok
26020 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
26030 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 ex_leave]([sqlit
26040 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 e3_db_mutex](D))
26050 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 after.** all ca
26060 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 lls to the inter
26070 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 faces listed her
26080 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e e are completed.
26090 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 .**.** If an int
260a0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 erface fails wit
260b0 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c h SQLITE_MISUSE,
260c0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 that means the
260d0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 interface.** was
260e0 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 invoked incorre
260f0 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c ctly by the appl
26100 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 ication. In tha
26110 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 t case, the.** e
26120 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 rror code and me
26130 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 ssage may or may
26140 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a not be set..*/.
26150 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
26160 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
26170 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 lite3_errcode(sq
26180 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 lite3 *db);.SQLI
26190 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
261a0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
261b0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
261c0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b de(sqlite3 *db);
261d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
261e0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 t char *SQLITE_S
261f0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 TDCALL sqlite3_e
26200 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b rrmsg(sqlite3*);
26210 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
26220 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 t void *SQLITE_S
26230 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 TDCALL sqlite3_e
26240 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a rrmsg16(sqlite3*
26250 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
26260 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 nst char *SQLITE
26270 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
26280 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f _errstr(int);../
26290 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 *.** CAPI3REF: P
262a0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
262b0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 t Object.** KEYW
262c0 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 ORDS: {prepared
262d0 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 statement} {prep
262e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d ared statements}
262f0 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
26300 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
26310 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 t represents a s
26320 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d ingle SQL statem
26330 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 ent that.** has
26340 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e been compiled in
26350 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 to binary form a
26360 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 nd is ready to b
26370 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a e evaluated..**.
26380 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 ** Think of each
26390 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
263a0 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d s a separate com
263b0 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 puter program.
263c0 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 The.** original
263d0 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 SQL text is sour
263e0 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 ce code. A prep
263f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f ared statement o
26400 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 bject .** is the
26410 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 compiled object
26420 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 code. All SQL
26430 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
26440 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 d into a.** prep
26450 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 ared statement b
26460 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 efore it can be
26470 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c run..**.** The l
26480 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 ife-cycle of a p
26490 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
264a0 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 t object usually
264b0 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a goes like this:
264c0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c .**.** <ol>.** <
264d0 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 li> Create the p
264e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
264f0 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b t object using [
26500 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
26510 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 v2()]..** <li> B
26520 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 ind values to [p
26530 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 arameters] using
26540 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
26550 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e d_*().** in
26560 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 terfaces..** <li
26570 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 > Run the SQL by
26580 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
26590 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 3_step()] one or
265a0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
265b0 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 <li> Reset the p
265c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
265d0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
265e0 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 _reset()] then g
265f0 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 o back.** t
26600 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 o step 2. Do th
26610 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 is zero or more
26620 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 times..** <li> D
26630 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 estroy the objec
26640 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
26650 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a _finalize()]..**
26660 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 </ol>.*/.typede
26670 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
26680 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 _stmt sqlite3_st
26690 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 mt;../*.** CAPI3
266a0 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 REF: Run-time Li
266b0 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 mits.** METHOD:
266c0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 sqlite3.**.** ^(
266d0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 This interface a
266e0 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f llows the size o
266f0 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 f various constr
26700 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 ucts to be limit
26710 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 ed.** on a conne
26720 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 ction by connect
26730 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 ion basis. The
26740 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
26750 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 is the.** [datab
26760 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
26770 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 whose limit is t
26780 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 o be set or quer
26790 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 ied. The.** sec
267a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
267b0 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d one of the [lim
267c0 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 it categories] t
267d0 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 hat define a.**
267e0 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 class of constru
267f0 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c cts to be size l
26800 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 imited. The thi
26810 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rd parameter is
26820 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 the.** new limit
26830 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 for that constr
26840 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 uct.)^.**.** ^If
26850 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 the new limit i
26860 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d s a negative num
26870 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 ber, the limit i
26880 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 s unchanged..**
26890 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 ^(For each limit
268a0 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 category SQLITE
268b0 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f _LIMIT_<i>NAME</
268c0 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a i> there is a .*
268d0 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 * [limits | hard
268e0 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a upper bound].**
268f0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d set at compile-
26900 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 time by a C prep
26910 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 rocessor macro c
26920 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 alled.** [limits
26930 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 | SQLITE_MAX_<i
26940 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 >NAME</i>]..** (
26950 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e The "_LIMIT_" in
26960 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 the name is cha
26970 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e nged to "_MAX_".
26980 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 ))^.** ^Attempts
26990 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c to increase a l
269a0 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 imit above its h
269b0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 ard upper bound
269c0 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 are.** silently
269d0 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 truncated to the
269e0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e hard upper boun
269f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 d..**.** ^Regard
26a00 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
26a10 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 or not the limit
26a20 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 was changed, th
26a30 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c e .** [sqlite3_l
26a40 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 imit()] interfac
26a50 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 e returns the pr
26a60 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 ior value of the
26a70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 limit..** ^Henc
26a80 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 e, to find the c
26a90 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 urrent value of
26aa0 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 a limit without
26ab0 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 changing it,.**
26ac0 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 simply invoke th
26ad0 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 is interface wit
26ae0 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 h the third para
26af0 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e meter set to -1.
26b00 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 .**.** Run-time
26b10 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e limits are inten
26b20 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 ded for use in a
26b30 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
26b40 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 manage.** both
26b50 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e their own intern
26b60 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 al database and
26b70 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 also databases t
26b80 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c hat are controll
26b90 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 ed.** by untrust
26ba0 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 ed external sour
26bb0 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 ces. An example
26bc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 application mig
26bd0 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 ht be a.** web b
26be0 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 rowser that has
26bf0 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 its own database
26c00 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 s for storing hi
26c10 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 story and.** sep
26c20 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 arate databases
26c30 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 controlled by Ja
26c40 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 vaScript applica
26c50 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 tions downloaded
26c60 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 .** off the Inte
26c70 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 rnet. The inter
26c80 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 nal databases ca
26c90 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a n be given the.*
26ca0 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 * large, default
26cb0 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 limits. Databa
26cc0 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 ses managed by e
26cd0 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 xternal sources
26ce0 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 can.** be given
26cf0 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d much smaller lim
26d00 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 its designed to
26d10 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c prevent a denial
26d20 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 of service.** a
26d30 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 ttack. Develope
26d40 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 rs might also wa
26d50 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 nt to use the [s
26d60 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
26d70 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 rizer()].** inte
26d80 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 rface to further
26d90 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 control untrust
26da0 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a ed SQL. The siz
26db0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
26dc0 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 e.** created by
26dd0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 an untrusted scr
26de0 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 ipt can be conta
26df0 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a ined using the.*
26e00 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e * [max_page_coun
26e10 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a t] [PRAGMA]..**.
26e20 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 ** New run-time
26e30 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
26e40 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
26e50 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
26e60 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
26e70 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
26e80 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 LL sqlite3_limit
26e90 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 (sqlite3*, int i
26ea0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a d, int newVal);.
26eb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
26ec0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 Run-Time Limit
26ed0 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 Categories.** KE
26ee0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 YWORDS: {limit c
26ef0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 ategory} {*limit
26f00 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a categories}.**.
26f10 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
26f20 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 ts define variou
26f30 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 s performance li
26f40 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e mits.** that can
26f50 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 be lowered at r
26f60 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 un-time using [s
26f70 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e qlite3_limit()].
26f80 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 .** The synopsis
26f90 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 of the meanings
26fa0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 of the various
26fb0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 limits is shown
26fc0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 below..** Additi
26fd0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
26fe0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 is available at
26ff0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 [limits | Limit
27000 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a s in SQLite]..**
27010 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 .** <dl>.** [[SQ
27020 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
27030 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
27040 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 _LIMIT_LENGTH</d
27050 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
27060 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e ximum size of an
27070 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 y string or BLOB
27080 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 or table row, i
27090 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a n bytes.<dd>)^.*
270a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
270b0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d MIT_SQL_LENGTH]]
270c0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
270d0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f MIT_SQL_LENGTH</
270e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
270f0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
27100 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
27110 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 t, in bytes.</dd
27120 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
27130 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d TE_LIMIT_COLUMN]
27140 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
27150 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e IMIT_COLUMN</dt>
27160 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
27170 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f mum number of co
27180 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 lumns in a table
27190 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 definition or i
271a0 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 n the.** result
271b0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 set of a [SELECT
271c0 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d ] or the maximum
271d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
271e0 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a ns in an index.*
271f0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 * or in an ORDER
27200 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 BY or GROUP BY
27210 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a clause.</dd>)^.*
27220 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
27230 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d MIT_EXPR_DEPTH]]
27240 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
27250 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f MIT_EXPR_DEPTH</
27260 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
27270 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 aximum depth of
27280 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f the parse tree o
27290 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e n any expression
272a0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
272b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f [SQLITE_LIMIT_CO
272c0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 MPOUND_SELECT]]
272d0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
272e0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 IT_COMPOUND_SELE
272f0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 CT</dt>.** <dd>T
27300 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
27310 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 r of terms in a
27320 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 compound SELECT
27330 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 statement.</dd>)
27340 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
27350 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d _LIMIT_VDBE_OP]]
27360 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
27370 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e MIT_VDBE_OP</dt>
27380 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
27390 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e mum number of in
273a0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 structions in a
273b0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
273c0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 program.** used
273d0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 to implement an
273e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 SQL statement.
273f0 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f This limit is no
27400 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 t currently.** e
27410 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 nforced, though
27420 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 that might be ad
27430 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 ded in some futu
27440 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a re release of.**
27450 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a SQLite.</dd>)^.
27460 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
27470 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
27480 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 G]] ^(<dt>SQLITE
27490 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
274a0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ARG</dt>.** <dd>
274b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
274c0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
274d0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f on a function.</
274e0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
274f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
27500 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 HED]] ^(<dt>SQLI
27510 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
27520 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
27530 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
27540 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 of [ATTACH | at
27550 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 tached databases
27560 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ].)^</dd>.**.**
27570 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c [[SQLITE_LIMIT_L
27580 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
27590 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 TH]].** ^(<dt>SQ
275a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f LITE_LIMIT_LIKE_
275b0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f PATTERN_LENGTH</
275c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
275d0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
275e0 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 the pattern arg
275f0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 ument to the [LI
27600 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d KE] or.** [GLOB]
27610 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e operators.</dd>
27620 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
27630 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
27640 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c _NUMBER]].** ^(<
27650 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
27660 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c VARIABLE_NUMBER<
27670 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
27680 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 maximum index nu
27690 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 mber of any [par
276a0 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 ameter] in an SQ
276b0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a L statement.)^.*
276c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
276d0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 MIT_TRIGGER_DEPT
276e0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
276f0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 _LIMIT_TRIGGER_D
27700 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 EPTH</dt>.** <dd
27710 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 >The maximum dep
27720 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 th of recursion
27730 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 for triggers.</d
27740 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
27750 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 ITE_LIMIT_WORKER
27760 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 _THREADS]] ^(<dt
27770 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f >SQLITE_LIMIT_WO
27780 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 RKER_THREADS</dt
27790 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
277a0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 imum number of a
277b0 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 uxiliary worker
277c0 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73 threads that a s
277d0 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 ingle.** [prepar
277e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 ed statement] ma
277f0 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a y start.</dd>)^.
27800 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
27810 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
27820 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
27830 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 0.#de
27840 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
27850 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 T_SQL_LENGTH
27860 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 1.#d
27870 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
27880 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 IT_COLUMN
27890 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 2.#
278a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
278b0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 MIT_EXPR_DEPTH
278c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 3.
278d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
278e0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
278f0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 LECT 4
27900 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
27910 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 LIMIT_VDBE_OP
27920 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
27930 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
27940 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
27950 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 ARG
27960 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
27970 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 E_LIMIT_ATTACHED
27980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
27990 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
279a0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
279b0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 TTERN_LENGTH
279c0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
279d0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
279e0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 LE_NUMBER
279f0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 9.#define SQ
27a00 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
27a10 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 ER_DEPTH
27a20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 10.#define S
27a30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b QLITE_LIMIT_WORK
27a40 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 ER_THREADS
27a50 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 11../*.** C
27a60 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 API3REF: Compili
27a70 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d ng An SQL Statem
27a80 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ent.** KEYWORDS:
27a90 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 {SQL statement
27aa0 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 compiler}.** MET
27ab0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 HOD: sqlite3.**
27ac0 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c CONSTRUCTOR: sql
27ad0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
27ae0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 To execute an SQ
27af0 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 L query, it must
27b00 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c first be compil
27b10 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 ed into a byte-c
27b20 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 ode.** program u
27b30 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 sing one of thes
27b40 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a e routines..**.*
27b50 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
27b60 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 ment, "db", is a
27b70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
27b80 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 ction] obtained
27b90 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 from a.** prior
27ba0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 successful call
27bb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
27bc0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
27bd0 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b en_v2()] or.** [
27be0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
27bf0 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 ]. The database
27c00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 connection must
27c10 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 not have been c
27c20 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 losed..**.** The
27c30 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
27c40 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 , "zSql", is the
27c50 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
27c60 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 compiled, encod
27c70 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 ed.** as either
27c80 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e UTF-8 or UTF-16.
27c90 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 The sqlite3_pr
27ca0 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 epare() and sqli
27cb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
27cc0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 .** interfaces u
27cd0 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 se UTF-8, and sq
27ce0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
27cf0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
27d00 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 epare16_v2().**
27d10 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a use UTF-16..**.*
27d20 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 * ^If the nByte
27d30 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 argument is nega
27d40 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 tive, then zSql
27d50 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 is read up to th
27d60 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 e.** first zero
27d70 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 terminator. ^If
27d80 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 nByte is positiv
27d90 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 e, then it is th
27da0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 e.** number of b
27db0 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a ytes read from z
27dc0 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 Sql. ^If nByte
27dd0 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f is zero, then no
27de0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
27df0 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 tement is genera
27e00 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 ted..** If the c
27e10 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 aller knows that
27e20 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 the supplied st
27e30 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d ring is nul-term
27e40 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 inated, then.**
27e50 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c there is a small
27e60 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 performance adv
27e70 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e antage to passin
27e80 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d g an nByte param
27e90 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 eter that.** is
27ea0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
27eb0 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 tes in the input
27ec0 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 string <i>inclu
27ed0 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 ding</i>.** the
27ee0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a nul-terminator..
27ef0 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c **.** ^If pzTail
27f00 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 is not NULL the
27f10 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 n *pzTail is mad
27f20 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 e to point to th
27f30 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 e first byte.**
27f40 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 past the end of
27f50 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 the first SQL st
27f60 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e atement in zSql.
27f70 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 These routines
27f80 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 only.** compile
27f90 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 the first state
27fa0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f ment in zSql, so
27fb0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 *pzTail is left
27fc0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 pointing to.**
27fd0 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 what remains unc
27fe0 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ompiled..**.** ^
27ff0 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 *ppStmt is left
28000 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f pointing to a co
28010 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 mpiled [prepared
28020 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
28030 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 can be.** execu
28040 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
28050 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 e3_step()]. ^If
28060 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 there is an err
28070 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 or, *ppStmt is s
28080 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 et.** to NULL.
28090 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 ^If the input te
280a0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 xt contains no S
280b0 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 QL (if the input
280c0 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 is an empty.**
280d0 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d string or a comm
280e0 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d ent) then *ppStm
280f0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c t is set to NULL
28100 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 ..** The calling
28110 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 procedure is re
28120 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 sponsible for de
28130 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 leting the compi
28140 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 led.** SQL state
28150 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ment using [sqli
28160 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
28170 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e after it has fin
28180 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a ished with it..*
28190 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 * ppStmt may not
281a0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
281b0 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 ^On success, the
281c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
281d0 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 () family of rou
281e0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 tines return [SQ
281f0 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 LITE_OK];.** oth
28200 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
28210 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
28220 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
28230 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
28240 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
28250 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e repare16_v2() in
28260 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 terfaces are.**
28270 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
28280 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 all new programs
28290 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 . The two older
282a0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 interfaces are r
282b0 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 etained.** for b
282c0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
282d0 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 bility, but thei
282e0 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 r use is discour
282f0 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 aged..** ^In the
28300 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 "v2" interfaces
28310 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 , the prepared s
28320 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 tatement.** that
28330 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 is returned (th
28340 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
28350 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e object) contain
28360 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
28370 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 ** original SQL
28380 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 text. This cause
28390 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 s the [sqlite3_s
283a0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tep()] interface
283b0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 to.** behave di
283c0 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 fferently in thr
283d0 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c ee ways:.**.** <
283e0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e ol>.** <li>.** ^
283f0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
28400 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 schema changes,
28410 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 instead of retur
28420 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 ning [SQLITE_SCH
28430 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c EMA] as it.** al
28440 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c ways used to do,
28450 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
28460 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 ] will automatic
28470 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 ally recompile t
28480 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d he SQL.** statem
28490 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 ent and try to r
284a0 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 un it again. As
284b0 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f many as [SQLITE_
284c0 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 MAX_SCHEMA_RETRY
284d0 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c ].** retries wil
284e0 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 l occur before s
284f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 qlite3_step() gi
28500 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 ves up and retur
28510 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 ns an error..**
28520 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e </li>.**.** <li>
28530 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 .** ^When an err
28540 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 or occurs, [sqli
28550 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c te3_step()] will
28560 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 return one of t
28570 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b he detailed.** [
28580 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 error codes] or
28590 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
285a0 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 codes]. ^The le
285b0 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 gacy behavior wa
285c0 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 s that.** [sqlit
285d0 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 e3_step()] would
285e0 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 only return a g
285f0 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 eneric [SQLITE_E
28600 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 RROR] result cod
28610 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 e.** and the app
28620 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 lication would h
28630 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 ave to make a se
28640 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cond call to [sq
28650 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a lite3_reset()].*
28660 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 * in order to fi
28670 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e nd the underlyin
28680 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 g cause of the p
28690 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 roblem. With the
286a0 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a "v2" prepare.**
286b0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
286c0 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 underlying reas
286d0 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 on for the error
286e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d is returned imm
286f0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c ediately..** </l
28700 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a i>.**.** <li>.**
28710 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 ^If the specifi
28720 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f c value bound to
28730 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f [parameter | ho
28740 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e st parameter] in
28750 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 the .** WHERE c
28760 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c lause might infl
28770 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 uence the choice
28780 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 of query plan f
28790 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a or a statement,.
287a0 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 ** then the stat
287b0 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 ement will be au
287c0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f tomatically reco
287d0 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 mpiled, as if th
287e0 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a ere had been .**
287f0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 a schema change
28800 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 , on the first
28810 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
28820 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 call following
28830 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f any change.** to
28840 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 the [sqlite3_bi
28850 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e nd_text | bindin
28860 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 gs] of that [par
28870 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 ameter]. .** ^Th
28880 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 e specific value
28890 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 of WHERE-clause
288a0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 [parameter] mig
288b0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 ht influence the
288c0 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 .** choice of q
288d0 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 uery plan if the
288e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
288f0 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 e left-hand side
28900 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 of a [LIKE].**
28910 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 or [GLOB] operat
28920 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 or or if the par
28930 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 ameter is compar
28940 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 ed to an indexed
28950 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 column.** and t
28960 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c he [SQLITE_ENABL
28970 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 E_STAT3] compile
28980 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 -time option is
28990 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 enabled..** </li
289a0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 >.** </ol>.*/.SQ
289b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
289c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
289d0 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 te3_prepare(. s
289e0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
289f0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
28a00 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
28a10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
28a20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
28a30 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 atement, UTF-8 e
28a40 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
28a50 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
28a60 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
28a70 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
28a80 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
28a90 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
28aa0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
28ab0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
28ac0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a . const char **
28ad0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
28ae0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
28af0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
28b00 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 zSql */.);.SQLIT
28b10 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
28b20 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
28b30 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 _prepare_v2(. s
28b40 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
28b50 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
28b60 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
28b70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
28b80 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
28b90 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 atement, UTF-8 e
28ba0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
28bb0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
28bc0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
28bd0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
28be0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
28bf0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
28c00 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
28c10 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
28c20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a . const char **
28c30 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
28c40 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
28c50 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
28c60 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 zSql */.);.SQLIT
28c70 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
28c80 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
28c90 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 _prepare16(. sq
28ca0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
28cb0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
28cc0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
28cd0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 nst void *zSql,
28ce0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
28cf0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 tement, UTF-16 e
28d00 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
28d10 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
28d20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
28d30 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
28d40 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
28d50 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
28d60 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
28d70 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
28d80 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a . const void **
28d90 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
28da0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
28db0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
28dc0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 zSql */.);.SQLIT
28dd0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
28de0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
28df0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 _prepare16_v2(.
28e00 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
28e10 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
28e20 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
28e30 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 const void *zSq
28e40 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
28e50 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 statement, UTF-1
28e60 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6 encoded */. i
28e70 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
28e80 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
28e90 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
28ea0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
28eb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
28ec0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
28ed0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
28ee0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
28ef0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
28f00 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
28f10 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
28f20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f of zSql */.);../
28f30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
28f40 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d etrieving Statem
28f50 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f ent SQL.** METHO
28f60 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
28f70 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 **.** ^This inte
28f80 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
28f90 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 d to retrieve a
28fa0 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 saved copy of th
28fb0 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 e original.** SQ
28fc0 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 L text used to c
28fd0 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 reate a [prepare
28fe0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 d statement] if
28ff0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 that statement w
29000 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 as.** compiled u
29010 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c sing either [sql
29020 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
29030 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
29040 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
29050 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
29060 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 nst char *SQLITE
29070 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
29080 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d _sql(sqlite3_stm
29090 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
290a0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 * CAPI3REF: Dete
290b0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 rmine If An SQL
290c0 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 Statement Writes
290d0 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a The Database.**
290e0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
290f0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _stmt.**.** ^The
29100 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
29110 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 adonly(X) interf
29120 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 ace returns true
29130 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a (non-zero) if.*
29140 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 * and only if th
29150 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
29160 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e ement] X makes n
29170 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 o direct changes
29180 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 to.** the conte
29190 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 nt of the databa
291a0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e se file..**.** N
291b0 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 ote that [applic
291c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
291d0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a L functions] or.
291e0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c ** [virtual tabl
291f0 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 es] might change
29200 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e the database in
29210 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 directly as a si
29220 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 de effect. .**
29230 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 ^(For example, i
29240 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
29250 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 defines a funct
29260 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 ion "eval()" tha
29270 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c t .** calls [sql
29280 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 ite3_exec()], th
29290 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 en the following
292a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 SQL statement w
292b0 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 ould.** change t
292c0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
292d0 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 through side-ef
292e0 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c fects:.**.** <bl
292f0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
29300 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c * SELECT eval
29310 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 ('DELETE FROM t1
29320 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c ') FROM t2;.** <
29330 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
29340 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 e>.**.** But bec
29350 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 ause the [SELECT
29360 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 ] statement does
29370 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
29380 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a database file.**
29390 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 directly, sqlit
293a0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
293b0 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 () would still r
293c0 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a eturn true.)^.**
293d0 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e .** ^Transaction
293e0 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 control stateme
293f0 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 nts such as [BEG
29400 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b IN], [COMMIT], [
29410 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 ROLLBACK],.** [S
29420 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b AVEPOINT], and [
29430 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 RELEASE] cause s
29440 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
29450 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e only() to return
29460 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 true,.** since
29470 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 the statements t
29480 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 hemselves do not
29490 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 actually modify
294a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 the database bu
294b0 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 t.** rather they
294c0 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d control the tim
294d0 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 ing of when othe
294e0 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 r statements mod
294f0 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 ify the .** data
29500 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 base. ^The [ATT
29510 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 ACH] and [DETACH
29520 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 ] statements als
29530 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 o cause.** sqlit
29540 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
29550 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 () to return tru
29560 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 e since, while t
29570 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a hose statements.
29580 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f ** change the co
29590 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 nfiguration of a
295a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
295b0 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f tion, they do no
295c0 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 t make .** chang
295d0 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e es to the conten
295e0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 t of the databas
295f0 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e e files on disk.
29600 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
29610 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
29620 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 L sqlite3_stmt_r
29630 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f eadonly(sqlite3_
29640 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
29650 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
29660 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 etermine If A Pr
29670 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
29680 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a Has Been Reset.
29690 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
296a0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
296b0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f he sqlite3_stmt_
296c0 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 busy(S) interfac
296d0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 e returns true (
296e0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 non-zero) if the
296f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
29700 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 atement] S has b
29710 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c een stepped at l
29720 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 east once using
29730 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
29740 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 p(S)] but has ne
29750 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d ither run to com
29760 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 pletion (returne
29770 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e d.** [SQLITE_DON
29780 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 E] from [sqlite3
29790 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a _step(S)]) nor.*
297a0 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 * been reset usi
297b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
297c0 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c t(S)]. ^The sql
297d0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 ite3_stmt_busy(S
297e0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 ).** interface r
297f0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 eturns false if
29800 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e S is a NULL poin
29810 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f ter. If S is no
29820 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 t a .** NULL poi
29830 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 nter and is not
29840 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 a pointer to a v
29850 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 alid [prepared s
29860 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a tatement].** obj
29870 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 ect, then the be
29880 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
29890 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 ned and probably
298a0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a undesirable..**
298b0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
298c0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 ce can be used i
298d0 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 n combination [s
298e0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 qlite3_next_stmt
298f0 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 ()].** to locate
29900 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 all prepared st
29910 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 atements associa
29920 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 ted with a datab
29930 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 ase .** connecti
29940 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e on that are in n
29950 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 eed of being res
29960 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 et. This can be
29970 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 used,.** for ex
29980 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f ample, in diagno
29990 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f stic routines to
299a0 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 search for prep
299b0 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 ared .** stateme
299c0 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c nts that are hol
299d0 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 ding a transacti
299e0 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 on open..*/.SQLI
299f0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
29a00 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
29a10 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 3_stmt_busy(sqli
29a20 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
29a30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e ** CAPI3REF: Dyn
29a40 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 amically Typed V
29a50 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b alue Object.** K
29a60 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 EYWORDS: {protec
29a70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
29a80 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 e} {unprotected
29a90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a sqlite3_value}.*
29aa0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 *.** SQLite uses
29ab0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c the sqlite3_val
29ac0 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 ue object to rep
29ad0 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 resent all value
29ae0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 s.** that can be
29af0 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 stored in a dat
29b00 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c abase table. SQL
29b10 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
29b20 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 typing.** for t
29b30 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f he values it sto
29b40 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 res. ^Values st
29b50 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f ored in sqlite3_
29b60 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a value objects.**
29b70 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 can be integers
29b80 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 , floating point
29b90 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 values, strings
29ba0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c , BLOBs, or NULL
29bb0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 ..**.** An sqlit
29bc0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
29bd0 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 may be either "p
29be0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e rotected" or "un
29bf0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 protected"..** S
29c00 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 ome interfaces r
29c10 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 equire a protect
29c20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
29c30 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 . Other interfa
29c40 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 ces.** will acce
29c50 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 pt either a prot
29c60 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 ected or an unpr
29c70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
29c80 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 value..** Every
29c90 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 interface that a
29ca0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 ccepts sqlite3_v
29cb0 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 alue arguments s
29cc0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 pecifies.** whet
29cd0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 her or not it re
29ce0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 quires a protect
29cf0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
29d00 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 . The.** [sqlit
29d10 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 e3_value_dup()]
29d20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
29d30 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 used to constru
29d40 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f ct a new .** pro
29d50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
29d60 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 alue from an unp
29d70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
29d80 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 _value..**.** Th
29d90 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 e terms "protect
29da0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 ed" and "unprote
29db0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 cted" refer to w
29dc0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a hether or not.**
29dd0 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 a mutex is held
29de0 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d . An internal m
29df0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 utex is held for
29e00 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 a protected.**
29e10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
29e20 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 ject but no mute
29e30 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e x is held for an
29e40 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
29e50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
29e60 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 ject. If SQLite
29e70 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 is compiled to
29e80 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 be single-thread
29e90 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c ed.** (with [SQL
29ea0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
29eb0 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 ] and with [sqli
29ec0 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 te3_threadsafe()
29ed0 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a ] returning 0).*
29ee0 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 * or if SQLite i
29ef0 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 s run in one of
29f00 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f reduced mutex mo
29f10 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f des .** [SQLITE_
29f20 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
29f30 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f EAD] or [SQLITE_
29f40 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
29f50 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 AD].** then ther
29f60 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 e is no distinct
29f70 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 ion between prot
29f80 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 ected and unprot
29f90 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
29fa0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 _value objects a
29fb0 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 nd they can be u
29fc0 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 sed interchangea
29fd0 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a bly. However,.*
29fe0 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f * for maximum co
29ff0 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 de portability i
2a000 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 t is recommended
2a010 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f that applicatio
2a020 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 ns.** still make
2a030 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e the distinction
2a040 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 between protect
2a050 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 ed and unprotect
2a060 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
2a070 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e lue objects even
2a080 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 when not strict
2a090 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a ly required..**.
2a0a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2a0b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 value objects th
2a0c0 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 at are passed as
2a0d0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f parameters into
2a0e0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e the.** implemen
2a0f0 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 tation of [appli
2a100 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
2a110 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 QL functions] ar
2a120 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 e protected..**
2a130 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
2a140 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e ue object return
2a150 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 ed by.** [sqlite
2a160 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 3_column_value()
2a170 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 ] is unprotected
2a180 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 ..** Unprotected
2a190 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2a1a0 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 bjects may only
2a1b0 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 be used with.**
2a1c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
2a1d0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 value()] and [sq
2a1e0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 lite3_bind_value
2a1f0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c ()]..** The [sql
2a200 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 ite3_value_blob
2a210 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f | sqlite3_value_
2a220 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f type()] family o
2a230 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 f.** interfaces
2a240 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 require protecte
2a250 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
2a260 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 objects..*/.type
2a270 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 def struct Mem s
2a280 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f qlite3_value;../
2a290 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
2a2a0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 QL Function Cont
2a2b0 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a ext Object.**.**
2a2c0 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 The context in
2a2d0 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e which an SQL fun
2a2e0 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 ction executes i
2a2f0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a s stored in an.*
2a300 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 * sqlite3_contex
2a310 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f t object. ^A po
2a320 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 inter to an sqli
2a330 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 te3_context obje
2a340 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 ct.** is always
2a350 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
2a360 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d to [application-
2a370 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2a380 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 tions]..** The a
2a390 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2a3a0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ed SQL function
2a3b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
2a3c0 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a ill pass this.**
2a3d0 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 pointer through
2a3e0 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b into calls to [
2a3f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
2a400 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 nt | sqlite3_res
2a410 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ult()],.** [sqli
2a420 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
2a430 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 ntext()], [sqlit
2a440 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c e3_user_data()],
2a450 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
2a460 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 text_db_handle()
2a470 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f ], [sqlite3_get_
2a480 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 auxdata()],.** a
2a490 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 nd/or [sqlite3_s
2a4a0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a et_auxdata()]..*
2a4b0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
2a4c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
2a4d0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
2a4e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2a4f0 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 F: Binding Value
2a500 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 s To Prepared St
2a510 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 atements.** KEYW
2a520 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 ORDS: {host para
2a530 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 meter} {host par
2a540 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 ameters} {host p
2a550 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a arameter name}.*
2a560 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c * KEYWORDS: {SQL
2a570 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c parameter} {SQL
2a580 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 parameters} {pa
2a590 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d rameter binding}
2a5a0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
2a5b0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
2a5c0 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 (In the SQL stat
2a5d0 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 ement text input
2a5e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 to [sqlite3_pre
2a5f0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 pare_v2()] and i
2a600 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 ts variants,.**
2a610 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 literals may be
2a620 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 replaced by a [p
2a630 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d arameter] that m
2a640 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f atches one of fo
2a650 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c llowing.** templ
2a660 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ates:.**.** <ul>
2a670 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c .** <li> ?.** <
2a680 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 li> ?NNN.** <li
2a690 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 > :VVV.** <li>
2a6a0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 @VVV.** <li> $
2a6b0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a VVV.** </ul>.**.
2a6c0 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 ** In the templa
2a6d0 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 tes above, NNN r
2a6e0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 epresents an int
2a6f0 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a eger literal,.**
2a700 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 and VVV represe
2a710 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 nts an alphanume
2a720 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 ric identifier.)
2a730 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f ^ ^The values o
2a740 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d f these.** param
2a750 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c eters (also call
2a760 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 ed "host paramet
2a770 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 er names" or "SQ
2a780 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a L parameters").*
2a790 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 * can be set usi
2a7a0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ng the sqlite3_b
2a7b0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 ind_*() routines
2a7c0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a defined here..*
2a7d0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
2a7e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
2a7f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
2a800 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 routines is alw
2a810 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 ays.** a pointer
2a820 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
2a830 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 _stmt] object re
2a840 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b turned from.** [
2a850 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2a860 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 v2()] or its var
2a870 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 iants..**.** ^Th
2a880 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
2a890 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f t is the index o
2a8a0 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 f the SQL parame
2a8b0 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a ter to be set..*
2a8c0 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 * ^The leftmost
2a8d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 SQL parameter ha
2a8e0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e s an index of 1.
2a8f0 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 ^When the same
2a900 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 named.** SQL pa
2a910 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 rameter is used
2a920 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 more than once,
2a930 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 second and subse
2a940 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 quent.** occurre
2a950 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 nces have the sa
2a960 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 me index as the
2a970 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 first occurrence
2a980 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 ..** ^The index
2a990 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 for named parame
2a9a0 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b ters can be look
2a9b0 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a ed up using the.
2a9c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
2a9d0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
2a9e0 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 ()] API if desir
2a9f0 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a ed. ^The index.
2aa00 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 ** for "?NNN" pa
2aa10 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 rameters is the
2aa20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a value of NNN..**
2aa30 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 ^The NNN value
2aa40 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 must be between
2aa50 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 1 and the [sqlit
2aa60 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 e3_limit()].** p
2aa70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 arameter [SQLITE
2aa80 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
2aa90 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 NUMBER] (default
2aaa0 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a value: 999)..**
2aab0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 .** ^The third a
2aac0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 rgument is the v
2aad0 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 alue to bind to
2aae0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a the parameter..*
2aaf0 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 * ^If the third
2ab00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
2ab10 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
2ab20 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
2ab30 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 _text16().** or
2ab40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2ab50 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f b() is a NULL po
2ab60 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 inter then the f
2ab70 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a ourth parameter.
2ab80 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e ** is ignored an
2ab90 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 d the end result
2aba0 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 is the same as
2abb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c sqlite3_bind_nul
2abc0 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 l()..**.** ^(In
2abd0 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 those routines t
2abe0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 hat have a fourt
2abf0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 h argument, its
2ac00 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 value is the.**
2ac10 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2ac20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 in the parameter
2ac30 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 . To be clear:
2ac40 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 the value is the
2ac50 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 .** number of <u
2ac60 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 >bytes</u> in th
2ac70 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 e value, not the
2ac80 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
2ac90 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 cters.)^.** ^If
2aca0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
2acb0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
2acc0 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 bind_text() or s
2acd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2ace0 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 16().** is negat
2acf0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 ive, then the le
2ad00 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 ngth of the stri
2ad10 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d ng is.** the num
2ad20 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 ber of bytes up
2ad30 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 to the first zer
2ad40 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a o terminator..**
2ad50 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 If the fourth p
2ad60 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
2ad70 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 te3_bind_blob()
2ad80 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
2ad90 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f n.** the behavio
2ada0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a r is undefined..
2adb0 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 ** If a non-nega
2adc0 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 tive fourth para
2add0 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 meter is provide
2ade0 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e d to sqlite3_bin
2adf0 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 d_text().** or s
2ae00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2ae10 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 16() or sqlite3_
2ae20 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 bind_text64() th
2ae30 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d en.** that param
2ae40 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 eter must be the
2ae50 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 byte offset.**
2ae60 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 where the NUL te
2ae70 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f rminator would o
2ae80 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 ccur assuming th
2ae90 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 e string were NU
2aea0 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e L.** terminated.
2aeb0 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 If any NUL cha
2aec0 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 racters occur at
2aed0 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 byte offsets le
2aee0 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 ss than .** the
2aef0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 value of the fou
2af00 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 rth parameter th
2af10 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 en the resulting
2af20 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 string value wi
2af30 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d ll.** contain em
2af40 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 bedded NULs. Th
2af50 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 e result of expr
2af60 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e essions involvin
2af70 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 g strings.** wit
2af80 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 h embedded NULs
2af90 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
2afa0 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 .** ^The fifth a
2afb0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 rgument to the B
2afc0 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 LOB and string b
2afd0 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 inding interface
2afe0 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 s.** is a destru
2aff0 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 ctor used to dis
2b000 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 pose of the BLOB
2b010 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 or.** string af
2b020 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 ter SQLite has f
2b030 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e inished with it.
2b040 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f ^The destructo
2b050 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 r is called.** t
2b060 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 o dispose of the
2b070 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 BLOB or string
2b080 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c even if the call
2b090 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 to bind API fai
2b0a0 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 ls..** ^If the f
2b0b0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 ifth argument is
2b0c0 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 .** the special
2b0d0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 value [SQLITE_ST
2b0e0 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 ATIC], then SQLi
2b0f0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 te assumes that
2b100 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 the.** informati
2b110 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c on is in static,
2b120 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 unmanaged space
2b130 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 and does not ne
2b140 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a ed to be freed..
2b150 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 ** ^If the fifth
2b160 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 argument has th
2b170 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f e value [SQLITE_
2b180 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e TRANSIENT], then
2b190 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 .** SQLite makes
2b1a0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 its own private
2b1b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 copy of the dat
2b1c0 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 a immediately, b
2b1d0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c efore.** the sql
2b1e0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f ite3_bind_*() ro
2b1f0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a utine returns..*
2b200 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 *.** ^The sixth
2b210 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
2b220 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 te3_bind_text64(
2b230 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 ) must be one of
2b240 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 .** [SQLITE_UTF8
2b250 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 ], [SQLITE_UTF16
2b260 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 ], [SQLITE_UTF16
2b270 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f BE], or [SQLITE_
2b280 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 UTF16LE].** to s
2b290 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 pecify the encod
2b2a0 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 ing of the text
2b2b0 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 in the third par
2b2c0 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 ameter. If.** t
2b2d0 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e he sixth argumen
2b2e0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e t to sqlite3_bin
2b2f0 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f d_text64() is no
2b300 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 t one of the.**
2b310 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 allowed values s
2b320 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 hown above, or i
2b330 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 f the text encod
2b340 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 ing is different
2b350 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 .** from the enc
2b360 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 oding specified
2b370 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 by the sixth par
2b380 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 ameter, then the
2b390 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 behavior.** is
2b3a0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
2b3b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 ^The sqlite3_bi
2b3c0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f nd_zeroblob() ro
2b3d0 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c utine binds a BL
2b3e0 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 OB of length N t
2b3f0 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 hat.** is filled
2b400 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e with zeroes. ^
2b410 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 A zeroblob uses
2b420 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f a fixed amount o
2b430 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 f memory.** (jus
2b440 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 t an integer to
2b450 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 hold its size) w
2b460 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 hile it is being
2b470 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a processed..** Z
2b480 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 eroblobs are int
2b490 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 ended to serve a
2b4a0 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 s placeholders f
2b4b0 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a or BLOBs whose.*
2b4c0 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 * content is lat
2b4d0 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 er written using
2b4e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f .** [sqlite3_blo
2b4f0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 b_open | increme
2b500 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 ntal BLOB I/O] r
2b510 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e outines..** ^A n
2b520 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f egative value fo
2b530 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 r the zeroblob r
2b540 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f esults in a zero
2b550 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a -length BLOB..**
2b560 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 .** ^If any of t
2b570 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
2b580 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 *() routines are
2b590 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e called with a N
2b5a0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 ULL pointer.** f
2b5b0 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 or the [prepared
2b5c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 statement] or w
2b5d0 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 ith a prepared s
2b5e0 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 tatement for whi
2b5f0 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 ch.** [sqlite3_s
2b600 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 tep()] has been
2b610 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 called more rece
2b620 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 ntly than [sqlit
2b630 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 e3_reset()],.**
2b640 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 then the call wi
2b650 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
2b660 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 E_MISUSE]. If a
2b670 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f ny sqlite3_bind_
2b680 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 ().** routine is
2b690 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 passed a [prepa
2b6a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
2b6b0 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e hat has been fin
2b6c0 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 alized, the.** r
2b6d0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e esult is undefin
2b6e0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 ed and probably
2b6f0 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e harmful..**.** ^
2b700 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 Bindings are not
2b710 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 cleared by the
2b720 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2b730 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 ] routine..** ^U
2b740 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 nbound parameter
2b750 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 s are interprete
2b760 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a d as NULL..**.**
2b770 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 ^The sqlite3_bi
2b780 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 nd_* routines re
2b790 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
2b7a0 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 on success or a
2b7b0 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 n.** [error code
2b7c0 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f ] if anything go
2b7d0 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 es wrong..** ^[S
2b7e0 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 QLITE_TOOBIG] mi
2b7f0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 ght be returned
2b800 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 if the size of a
2b810 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a string or BLOB.
2b820 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 ** exceeds limit
2b830 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 s imposed by [sq
2b840 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 lite3_limit]([SQ
2b850 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
2b860 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 H]) or.** [SQLIT
2b870 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a E_MAX_LENGTH]..*
2b880 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 * ^[SQLITE_RANGE
2b890 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 ] is returned if
2b8a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a the parameter.*
2b8b0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f * index is out o
2b8c0 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 f range. ^[SQLI
2b8d0 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 TE_NOMEM] is ret
2b8e0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 urned if malloc(
2b8f0 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 ) fails..**.** S
2b900 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
2b910 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2b920 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 _count()],.** [s
2b930 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2b940 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 meter_name()], a
2b950 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 nd [sqlite3_bind
2b960 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
2b970 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
2b980 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2b990 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 DCALL sqlite3_bi
2b9a0 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f nd_blob(sqlite3_
2b9b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
2b9c0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 t void*, int n,
2b9d0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
2b9e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2b9f0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2ba00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2ba10 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 64(sqlite3_stmt*
2ba20 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
2ba30 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 d*, sqlite3_uint
2ba40 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 64,.
2ba50 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
2ba60 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c (*)(void*));.SQL
2ba70 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
2ba80 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2ba90 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 e3_bind_double(s
2baa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2bab0 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 t, double);.SQLI
2bac0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2bad0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2bae0 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 3_bind_int(sqlit
2baf0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 e3_stmt*, int, i
2bb00 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
2bb10 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2bb20 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f LL sqlite3_bind_
2bb30 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 int64(sqlite3_st
2bb40 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 mt*, int, sqlite
2bb50 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 3_int64);.SQLITE
2bb60 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
2bb70 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
2bb80 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 bind_null(sqlite
2bb90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 3_stmt*, int);.S
2bba0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2bbb0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2bbc0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 ite3_bind_text(s
2bbd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2bbe0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 ,const char*,int
2bbf0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 ,void(*)(void*))
2bc00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2bc10 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2bc20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2bc30 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t16(sqlite3_stmt
2bc40 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f *, int, const vo
2bc50 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a id*, int, void(*
2bc60 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
2bc70 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2bc80 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2bc90 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c _bind_text64(sql
2bca0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
2bcb0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 const char*, sq
2bcc0 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 lite3_uint64,.
2bcd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2bce0 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 void(*)(v
2bcf0 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 oid*), unsigned
2bd00 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a char encoding);.
2bd10 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
2bd20 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2bd30 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 lite3_bind_value
2bd40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2bd50 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 int, const sqlit
2bd60 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
2bd70 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2bd80 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2bd90 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 3_bind_zeroblob(
2bda0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2bdb0 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 53 51 4c 49 nt, int n);.SQLI
2bdc0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2bdd0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2bde0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 3_bind_zeroblob6
2bdf0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
2be00 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 int, sqlite3_ui
2be10 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt64);../*.** CA
2be20 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f PI3REF: Number O
2be30 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 f SQL Parameters
2be40 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
2be50 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
2be60 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e This routine can
2be70 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 be used to find
2be80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b the number of [
2be90 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a SQL parameters].
2bea0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 ** in a [prepare
2beb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 d statement]. S
2bec0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 QL parameters ar
2bed0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a e tokens of the.
2bee0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e ** form "?", "?N
2bef0 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 NN", ":AAA", "$A
2bf00 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 AA", or "@AAA" t
2bf10 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 hat serve as.**
2bf20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 placeholders for
2bf30 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 values that are
2bf40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2bf50 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 lob | bound].**
2bf60 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 to the parameter
2bf70 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d s at a later tim
2bf80 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 e..**.** ^(This
2bf90 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 routine actually
2bfa0 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 returns the ind
2bfb0 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 ex of the larges
2bfc0 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a t (rightmost).**
2bfd0 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 parameter. For
2bfe0 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 all forms except
2bff0 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c ?NNN, this will
2c000 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 correspond to t
2c010 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
2c020 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 unique parameter
2c030 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 s. If parameter
2c040 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f s of the ?NNN fo
2c050 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 rm are used,.**
2c060 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 there may be gap
2c070 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e s in the list.)^
2c080 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2c090 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2c0a0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
2c0b0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
2c0c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2c0d0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 name()], and.**
2c0e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2c0f0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
2c100 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
2c110 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2c120 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f LL sqlite3_bind_
2c130 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
2c140 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
2c150 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2c160 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 Name Of A Host
2c170 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 Parameter.** MET
2c180 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
2c190 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c t.**.** ^The sql
2c1a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2c1b0 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e ter_name(P,N) in
2c1c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a terface returns.
2c1d0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ** the name of t
2c1e0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 he N-th [SQL par
2c1f0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b ameter] in the [
2c200 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2c210 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 nt] P..** ^(SQL
2c220 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 parameters of th
2c230 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 e form "?NNN" or
2c240 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 ":AAA" or "@AAA
2c250 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 " or "$AAA".** h
2c260 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 ave a name which
2c270 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 is the string "
2c280 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 ?NNN" or ":AAA"
2c290 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 or "@AAA" or "$A
2c2a0 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 AA".** respectiv
2c2b0 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 ely..** In other
2c2c0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 words, the init
2c2d0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f ial ":" or "$" o
2c2e0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 r "@" or "?".**
2c2f0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 is included as p
2c300 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e art of the name.
2c310 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 )^.** ^Parameter
2c320 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f s of the form "?
2c330 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c " without a foll
2c340 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 owing integer ha
2c350 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e ve no name.** an
2c360 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 d are referred t
2c370 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 o as "nameless"
2c380 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 or "anonymous pa
2c390 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a rameters"..**.**
2c3a0 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 ^The first host
2c3b0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 parameter has a
2c3c0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f n index of 1, no
2c3d0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 t 0..**.** ^If t
2c3e0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 he value N is ou
2c3f0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 t of range or if
2c400 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 the N-th parame
2c410 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 ter is.** namele
2c420 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 ss, then NULL is
2c430 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 returned. ^The
2c440 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
2c450 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e is.** always in
2c460 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 UTF-8 encoding
2c470 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 even if the name
2c480 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a d parameter was.
2c490 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 ** originally sp
2c4a0 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 ecified as UTF-1
2c4b0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 6 in [sqlite3_pr
2c4c0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a epare16()] or.**
2c4d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2c4e0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a e16_v2()]..**.**
2c4f0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
2c500 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
2c510 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a lite3_bind()],.*
2c520 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2c530 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
2c540 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
2c550 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2c560 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a er_index()]..*/.
2c570 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2c580 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 char *SQLITE_ST
2c590 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 DCALL sqlite3_bi
2c5a0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
2c5b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2c5c0 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 int);../*.** CA
2c5d0 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 PI3REF: Index Of
2c5e0 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 A Parameter Wit
2c5f0 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a h A Given Name.*
2c600 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
2c610 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 3_stmt.**.** ^Re
2c620 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f turn the index o
2c630 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 f an SQL paramet
2c640 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d er given its nam
2c650 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 e. ^The.** inde
2c660 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 x value returned
2c670 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 is suitable for
2c680 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f use as the seco
2c690 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 nd.** parameter
2c6a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 to [sqlite3_bind
2c6b0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
2c6c0 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a nd()]. ^A zero.
2c6d0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ** is returned i
2c6e0 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 f no matching pa
2c6f0 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 rameter is found
2c700 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 . ^The paramete
2c710 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 r.** name must b
2c720 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 e given in UTF-8
2c730 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 even if the ori
2c740 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a ginal statement.
2c750 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 ** was prepared
2c760 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 from UTF-16 text
2c770 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
2c780 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
2c790 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2c7a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2c7b0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
2c7c0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
2c7d0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2c7e0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a count()], and.**
2c7f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
2c800 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d arameter_name()]
2c810 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
2c820 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2c830 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f LL sqlite3_bind_
2c840 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
2c850 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 sqlite3_stmt*, c
2c860 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
2c870 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2c880 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 EF: Reset All Bi
2c890 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 ndings On A Prep
2c8a0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a ared Statement.*
2c8b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
2c8c0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 3_stmt.**.** ^Co
2c8d0 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e ntrary to the in
2c8e0 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c tuition of many,
2c8f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2c900 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 )] does not rese
2c910 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 t.** the [sqlite
2c920 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 3_bind_blob | bi
2c930 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 ndings] on a [pr
2c940 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2c950 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 ]..** ^Use this
2c960 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 routine to reset
2c970 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 all host parame
2c980 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f ters to NULL..*/
2c990 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2c9a0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2c9b0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e qlite3_clear_bin
2c9c0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 dings(sqlite3_st
2c9d0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
2c9e0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 I3REF: Number Of
2c9f0 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 Columns In A Re
2ca00 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 sult Set.** METH
2ca10 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2ca20 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 .**.** ^Return t
2ca30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
2ca40 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 umns in the resu
2ca50 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 lt set returned
2ca60 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 by the.** [prepa
2ca70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
2ca80 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 ^This routine re
2ca90 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 turns 0 if pStmt
2caa0 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 is an SQL.** st
2cab0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 atement that doe
2cac0 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 s not return dat
2cad0 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 a (for example a
2cae0 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a n [UPDATE])..**.
2caf0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
2cb00 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
2cb10 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ()].*/.SQLITE_AP
2cb20 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
2cb30 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
2cb40 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 umn_count(sqlite
2cb50 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
2cb60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2cb70 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e Column Names In
2cb80 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a A Result Set.**
2cb90 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2cba0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _stmt.**.** ^The
2cbb0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
2cbc0 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 rn the name assi
2cbd0 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 gned to a partic
2cbe0 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 ular column.** i
2cbf0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 n the result set
2cc00 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 of a [SELECT] s
2cc10 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 tatement. ^The
2cc20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
2cc30 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 ame().** interfa
2cc40 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
2cc50 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 nter to a zero-t
2cc60 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
2cc70 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 string.** and sq
2cc80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
2cc90 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 e16() returns a
2cca0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 pointer to a zer
2ccb0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
2ccc0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 UTF-16 string.
2ccd0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d ^The first param
2cce0 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 eter is the [pre
2ccf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2cd00 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 .** that impleme
2cd10 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d nts the [SELECT]
2cd20 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 statement. ^The
2cd30 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
2cd40 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 r is the.** colu
2cd50 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 mn number. ^The
2cd60 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e leftmost column
2cd70 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a is number 0..**
2cd80 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 .** ^The returne
2cd90 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 d string pointer
2cda0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 is valid until
2cdb0 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 either the [prep
2cdc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
2cdd0 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 ** is destroyed
2cde0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 by [sqlite3_fina
2cdf0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c lize()] or until
2ce00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
2ce10 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a s automatically.
2ce20 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 ** reprepared by
2ce30 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 the first call
2ce40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
2ce50 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 ()] for a partic
2ce60 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 ular run.** or u
2ce70 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 ntil the next ca
2ce80 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ll to.** sqlite3
2ce90 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f _column_name() o
2cea0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
2ceb0 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 _name16() on the
2cec0 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a same column..**
2ced0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f .** ^If sqlite3_
2cee0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 malloc() fails d
2cef0 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 uring the proces
2cf00 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 sing of either r
2cf10 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 outine.** (for e
2cf20 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 xample during a
2cf30 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 conversion from
2cf40 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 UTF-8 to UTF-16)
2cf50 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 then a.** NULL
2cf60 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 pointer is retur
2cf70 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
2cf80 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 name of a result
2cf90 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 column is the v
2cfa0 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 alue of the "AS"
2cfb0 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 clause for.** t
2cfc0 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 hat column, if t
2cfd0 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c here is an AS cl
2cfe0 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 ause. If there
2cff0 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a is no AS clause.
2d000 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 ** then the name
2d010 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 of the column i
2d020 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e s unspecified an
2d030 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f d may change fro
2d040 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 m.** one release
2d050 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 of SQLite to th
2d060 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 e next..*/.SQLIT
2d070 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
2d080 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
2d090 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2d0a0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
2d0b0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 t*, int N);.SQLI
2d0c0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
2d0d0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
2d0e0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e L sqlite3_column
2d0f0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
2d100 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a stmt*, int N);..
2d110 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2d120 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 Source Of Data I
2d130 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 n A Query Result
2d140 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
2d150 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
2d160 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 These routines p
2d170 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 rovide a means t
2d180 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 o determine the
2d190 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c database, table,
2d1a0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f and.** table co
2d1b0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 lumn that is the
2d1c0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 origin of a par
2d1d0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 ticular result c
2d1e0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c olumn in.** [SEL
2d1f0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a ECT] statement..
2d200 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 ** ^The name of
2d210 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 the database or
2d220 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 table or column
2d230 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 can be returned
2d240 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 as.** either a U
2d250 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 TF-8 or UTF-16 s
2d260 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 tring. ^The _da
2d270 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 tabase_ routines
2d280 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 return.** the d
2d290 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 atabase name, th
2d2a0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e e _table_ routin
2d2b0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 es return the ta
2d2c0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a ble name, and.**
2d2d0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 the origin_ rou
2d2e0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
2d2f0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a column name..**
2d300 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
2d310 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 tring is valid u
2d320 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 ntil the [prepar
2d330 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 ed statement] is
2d340 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 destroyed.** us
2d350 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
2d360 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 alize()] or unti
2d370 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 l the statement
2d380 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 is automatically
2d390 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 .** reprepared b
2d3a0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c y the first call
2d3b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
2d3c0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 p()] for a parti
2d3d0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 cular run.** or
2d3e0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 until the same i
2d3f0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 nformation is re
2d400 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e quested.** again
2d410 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 in a different
2d420 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 encoding..**.**
2d430 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 ^The names retur
2d440 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 ned are the orig
2d450 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 inal un-aliased
2d460 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 names of the.**
2d470 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c database, table,
2d480 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a and column..**.
2d490 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
2d4a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 gument to these
2d4b0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 interfaces is a
2d4c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2d4d0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 ent]..** ^These
2d4e0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
2d4f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
2d500 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c ut the Nth resul
2d510 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 t column returne
2d520 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 d by.** the stat
2d530 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 ement, where N i
2d540 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e s the second fun
2d550 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a ction argument..
2d560 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 ** ^The left-mos
2d570 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 t column is colu
2d580 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 mn 0 for these r
2d590 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e outines..**.** ^
2d5a0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d If the Nth colum
2d5b0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 n returned by th
2d5c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
2d5d0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a n expression or.
2d5e0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 ** subquery and
2d5f0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 is not a column
2d600 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 value, then all
2d610 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f of these functio
2d620 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c ns return.** NUL
2d630 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 L. ^These routi
2d640 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 ne might also re
2d650 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d turn NULL if a m
2d660 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
2d670 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 error.** occurs
2d680 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 . ^Otherwise, t
2d690 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e hey return the n
2d6a0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 ame of the attac
2d6b0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 hed database, ta
2d6c0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d ble,.** or colum
2d6d0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 n that query res
2d6e0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 ult column was e
2d6f0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a xtracted from..*
2d700 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c *.** ^As with al
2d710 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 l other SQLite A
2d720 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 PIs, those whose
2d730 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 names end with
2d740 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 "16" return.** U
2d750 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 TF-16 encoded st
2d760 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 rings and the ot
2d770 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 her functions re
2d780 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a turn UTF-8..**.*
2d790 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 * ^These APIs ar
2d7a0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 e only available
2d7b0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 if the library
2d7c0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 was compiled wit
2d7d0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 h the.** [SQLITE
2d7e0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d _ENABLE_COLUMN_M
2d7f0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 ETADATA] C-prepr
2d800 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a ocessor symbol..
2d810 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 **.** If two or
2d820 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c more threads cal
2d830 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 l one or more of
2d840 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
2d850 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 against the same
2d860 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 .** prepared sta
2d870 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d tement and colum
2d880 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 n at the same ti
2d890 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 me then the resu
2d8a0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 lts are.** undef
2d8b0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 ined..**.** If t
2d8c0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 wo or more threa
2d8d0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d ds call one or m
2d8e0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ore.** [sqlite3_
2d8f0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
2d900 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 name | column me
2d910 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 tadata interface
2d920 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 s].** for the sa
2d930 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 me [prepared sta
2d940 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 tement] and resu
2d950 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 lt column.** at
2d960 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 the same time th
2d970 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 en the results a
2d980 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f re undefined..*/
2d990 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2d9a0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 t char *SQLITE_S
2d9b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
2d9c0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e olumn_database_n
2d9d0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
2d9e0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 *,int);.SQLITE_A
2d9f0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 PI const void *S
2da00 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2da10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
2da20 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c abase_name16(sql
2da30 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
2da40 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2da50 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 t char *SQLITE_S
2da60 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
2da70 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 olumn_table_name
2da80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2da90 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
2daa0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 const void *SQLI
2dab0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2dac0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f e3_column_table_
2dad0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
2dae0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 tmt*,int);.SQLIT
2daf0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
2db00 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
2db10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2db20 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 origin_name(sqli
2db30 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
2db40 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2db50 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
2db60 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f DCALL sqlite3_co
2db70 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
2db80 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2db90 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ,int);../*.** CA
2dba0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 PI3REF: Declared
2dbb0 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 Datatype Of A Q
2dbc0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d uery Result.** M
2dbd0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2dbe0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 tmt.**.** ^(The
2dbf0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
2dc00 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 is a [prepared s
2dc10 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 tatement]..** If
2dc20 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 this statement
2dc30 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 is a [SELECT] st
2dc40 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 atement and the
2dc50 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 Nth column of th
2dc60 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 e.** returned re
2dc70 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 sult set of that
2dc80 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 [SELECT] is a t
2dc90 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 able column (not
2dca0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f an.** expressio
2dcb0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 n or subquery) t
2dcc0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 hen the declared
2dcd0 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 type of the tab
2dce0 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 le.** column is
2dcf0 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 returned.)^ ^If
2dd00 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
2dd10 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
2dd20 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 t is an.** expre
2dd30 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 ssion or subquer
2dd40 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 y, then a NULL p
2dd50 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ointer is return
2dd60 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 ed..** ^The retu
2dd70 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 rned string is a
2dd80 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f lways UTF-8 enco
2dd90 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 ded..**.** ^(For
2dda0 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 example, given
2ddb0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 the database sch
2ddc0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 ema:.**.** CREAT
2ddd0 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 E TABLE t1(c1 VA
2dde0 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e RIANT);.**.** an
2ddf0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 d the following
2de00 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 statement to be
2de10 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 compiled:.**.**
2de20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 SELECT c1 + 1, c
2de30 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 1 FROM t1;.**.**
2de40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f this routine wo
2de50 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 uld return the s
2de60 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 tring "VARIANT"
2de70 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 for the second r
2de80 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 esult.** column
2de90 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 (i==1), and a NU
2dea0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 LL pointer for t
2deb0 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 he first result
2dec0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e column (i==0).)^
2ded0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 .**.** ^SQLite u
2dee0 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d ses dynamic run-
2def0 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 time typing. ^S
2df00 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 o just because a
2df10 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 column.** is de
2df20 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 clared to contai
2df30 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 n a particular t
2df40 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 ype does not mea
2df50 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 n that the.** da
2df60 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 ta stored in tha
2df70 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 t column is of t
2df80 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 he declared type
2df90 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 . SQLite is.**
2dfa0 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 strongly typed,
2dfb0 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 but the typing i
2dfc0 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 s dynamic not st
2dfd0 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 atic. ^Type.**
2dfe0 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 is associated wi
2dff0 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 th individual va
2e000 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 lues, not with t
2e010 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a he containers.**
2e020 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 used to hold th
2e030 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 ose values..*/.S
2e040 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2e050 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 char *SQLITE_STD
2e060 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
2e070 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c umn_decltype(sql
2e080 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
2e090 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2e0a0 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 t void *SQLITE_S
2e0b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
2e0c0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 olumn_decltype16
2e0d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2e0e0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
2e0f0 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 3REF: Evaluate A
2e100 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a n SQL Statement.
2e110 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2e120 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 e3_stmt.**.** Af
2e130 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 ter a [prepared
2e140 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 statement] has b
2e150 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 een prepared usi
2e160 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 ng either.** [sq
2e170 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2e180 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2e190 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 prepare16_v2()]
2e1a0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 or one of the le
2e1b0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
2e1c0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 es [sqlite3_prep
2e1d0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 are()] or [sqlit
2e1e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c e3_prepare16()],
2e1f0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a this function.*
2e200 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 * must be called
2e210 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
2e220 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 es to evaluate t
2e230 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a he statement..**
2e240 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 .** The details
2e250 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 of the behavior
2e260 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 of the sqlite3_s
2e270 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 tep() interface
2e280 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 depend.** on whe
2e290 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 ther the stateme
2e2a0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 nt was prepared
2e2b0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 using the newer
2e2c0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a "v2" interface.*
2e2d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
2e2e0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
2e2f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2e300 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 v2()] or the old
2e310 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 er legacy.** int
2e320 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f erface [sqlite3_
2e330 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
2e340 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2e350 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 6()]. The use o
2e360 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 f the.** new "v2
2e370 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
2e380 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e ecommended for n
2e390 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
2e3a0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a but the legacy.*
2e3b0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c * interface will
2e3c0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 continue to be
2e3d0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a supported..**.**
2e3e0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 ^In the legacy
2e3f0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 interface, the r
2e400 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c eturn value will
2e410 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 be either [SQLI
2e420 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 TE_BUSY],.** [SQ
2e430 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c LITE_DONE], [SQL
2e440 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 ITE_ROW], [SQLIT
2e450 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 E_ERROR], or [SQ
2e460 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a LITE_MISUSE]..**
2e470 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 ^With the "v2"
2e480 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f interface, any o
2e490 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 f the other [res
2e4a0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a ult codes] or.**
2e4b0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
2e4c0 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 t codes] might b
2e4d0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 e returned as we
2e4e0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 ll..**.** ^[SQLI
2e4f0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 TE_BUSY] means t
2e500 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 hat the database
2e510 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 engine was unab
2e520 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 le to acquire th
2e530 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f e.** database lo
2e540 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 cks it needs to
2e550 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 do its job. ^If
2e560 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
2e570 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 s a [COMMIT].**
2e580 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 or occurs outsid
2e590 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 e of an explicit
2e5a0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 transaction, th
2e5b0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 en you can retry
2e5c0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e the.** statemen
2e5d0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 t. If the state
2e5e0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 ment is not a [C
2e5f0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 OMMIT] and occur
2e600 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 s within an.** e
2e610 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
2e620 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f ion then you sho
2e630 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 uld rollback the
2e640 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 transaction bef
2e650 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e ore.** continuin
2e660 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 g..**.** ^[SQLIT
2e670 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 E_DONE] means th
2e680 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 at the statement
2e690 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 has finished ex
2e6a0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 ecuting.** succe
2e6b0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 ssfully. sqlite
2e6c0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 3_step() should
2e6d0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 not be called ag
2e6e0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 ain on this virt
2e6f0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 ual.** machine w
2e700 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c ithout first cal
2e710 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 ling [sqlite3_re
2e720 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 set()] to reset
2e730 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d the virtual.** m
2e740 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 achine back to i
2e750 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 ts initial state
2e760 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
2e770 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 SQL statement be
2e780 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 ing executed ret
2e790 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 urns any data, t
2e7a0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d hen [SQLITE_ROW]
2e7b0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
2e7c0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 each time a new
2e7d0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 row of data is r
2e7e0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 eady for process
2e7f0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 ing by the.** ca
2e800 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 ller. The values
2e810 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 may be accessed
2e820 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 using the [colu
2e830 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 mn access functi
2e840 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 ons]..** sqlite3
2e850 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 _step() is calle
2e860 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 d again to retri
2e870 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 eve the next row
2e880 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 of data..**.**
2e890 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 ^[SQLITE_ERROR]
2e8a0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e means that a run
2e8b0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 -time error (suc
2e8c0 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e h as a constrain
2e8d0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 t.** violation)
2e8e0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 has occurred. s
2e8f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
2e900 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
2e910 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 ed again on.** t
2e920 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f he VM. More info
2e930 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 rmation may be f
2e940 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 ound by calling
2e950 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
2e960 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 )]..** ^With the
2e970 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
2e980 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 e, a more specif
2e990 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 ic error code (f
2e9a0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b or example,.** [
2e9b0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
2e9c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d ], [SQLITE_SCHEM
2e9d0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 A], [SQLITE_CORR
2e9e0 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 UPT], and so for
2e9f0 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 th).** can be ob
2ea00 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e tained by callin
2ea10 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
2ea20 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 ()] on the.** [p
2ea30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2ea40 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 t]. ^In the "v2
2ea50 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 " interface,.**
2ea60 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 the more specifi
2ea70 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 c error code is
2ea80 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c returned directl
2ea90 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 y by sqlite3_ste
2eaa0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 p()..**.** [SQLI
2eab0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 TE_MISUSE] means
2eac0 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 that the this r
2ead0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 outine was calle
2eae0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c d inappropriatel
2eaf0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 y..** Perhaps it
2eb00 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 was called on a
2eb10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2eb20 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a ment] that has.*
2eb30 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b * already been [
2eb40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2eb50 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 | finalized] or
2eb60 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 on one that had
2eb70 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 .** previously r
2eb80 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
2eb90 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 ERROR] or [SQLIT
2eba0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 E_DONE]. Or it
2ebb0 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 could.** be the
2ebc0 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 case that the sa
2ebd0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
2ebe0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 ection is being
2ebf0 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a used by two or.*
2ec00 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 * more threads a
2ec10 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e t the same momen
2ec20 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a t in time..**.**
2ec30 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e For all version
2ec40 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 s of SQLite up t
2ec50 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 o and including
2ec60 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 3.6.23.1, a call
2ec70 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
2ec80 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 reset()] was req
2ec90 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 uired after sqli
2eca0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 te3_step() retur
2ecb0 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 ned anything.**
2ecc0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
2ecd0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 TE_ROW] before a
2ece0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e ny subsequent in
2ecf0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 vocation of.** s
2ed00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
2ed10 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 Failure to reset
2ed20 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
2ed30 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a atement using .*
2ed40 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
2ed50 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 ()] would result
2ed60 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d in an [SQLITE_M
2ed70 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 ISUSE] return fr
2ed80 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 om.** sqlite3_st
2ed90 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 ep(). But after
2eda0 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e version 3.6.23.
2edb0 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 1, sqlite3_step(
2edc0 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 ) began.** calli
2edd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
2ede0 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c t()] automatical
2edf0 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 ly in this circu
2ee00 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a mstance rather.*
2ee10 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 * than returning
2ee20 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
2ee30 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 . This is not c
2ee40 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 onsidered a comp
2ee50 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 atibility.** bre
2ee60 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 ak because any a
2ee70 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 pplication that
2ee80 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e ever receives an
2ee90 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 SQLITE_MISUSE e
2eea0 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 rror.** is broke
2eeb0 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e n by definition.
2eec0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d The [SQLITE_OM
2eed0 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f IT_AUTORESET] co
2eee0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
2eef0 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 n.** can be used
2ef00 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 to restore the
2ef10 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e legacy behavior.
2ef20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 .**.** <b>Goofy
2ef30 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a Interface Alert:
2ef40 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 </b> In the lega
2ef50 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 cy interface, th
2ef60 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 e sqlite3_step()
2ef70 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 .** API always r
2ef80 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 eturns a generic
2ef90 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 error code, [SQ
2efa0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c LITE_ERROR], fol
2efb0 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 lowing any.** er
2efc0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ror other than [
2efd0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 SQLITE_BUSY] and
2efe0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
2eff0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c . You must call
2f000 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
2f010 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 et()] or [sqlite
2f020 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 3_finalize()] in
2f030 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f order to find o
2f040 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 ne of the.** spe
2f050 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 cific [error cod
2f060 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 es] that better
2f070 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
2f080 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 ror..** We admit
2f090 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 that this is a
2f0a0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 goofy design. T
2f0b0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 he problem has b
2f0c0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 een fixed.** wit
2f0d0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 h the "v2" inter
2f0e0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 face. If you pr
2f0f0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 epare all of you
2f100 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 r SQL statements
2f110 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 .** using either
2f120 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2f130 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
2f140 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2f150 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f ()] instead.** o
2f160 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 f the legacy [sq
2f170 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
2f180 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
2f190 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 epare16()] inter
2f1a0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 faces,.** then t
2f1b0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 he more specific
2f1c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 [error codes] a
2f1d0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 re returned dire
2f1e0 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 ctly.** by sqlit
2f1f0 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 e3_step(). The
2f200 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 use of the "v2"
2f210 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 interface is rec
2f220 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c ommended..*/.SQL
2f230 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
2f240 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2f250 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f e3_step(sqlite3_
2f260 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
2f270 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
2f280 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 of columns in a
2f290 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 result set.** ME
2f2a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2f2b0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 mt.**.** ^The sq
2f2c0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
2f2d0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (P) interface re
2f2e0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
2f2f0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
2f300 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f he.** current ro
2f310 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 w of the result
2f320 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 set of [prepared
2f330 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a statement] P..*
2f340 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 * ^If prepared s
2f350 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 tatement P does
2f360 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 not have results
2f370 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e ready to return
2f380 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 .** (via calls t
2f390 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 o the [sqlite3_c
2f3a0 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 olumn_int | sqli
2f3b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 te3_column_*()]
2f3c0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 of.** interfaces
2f3d0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 ) then sqlite3_d
2f3e0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 ata_count(P) ret
2f3f0 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 urns 0..** ^The
2f400 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
2f410 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c nt(P) routine al
2f420 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 so returns 0 if
2f430 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e P is a NULL poin
2f440 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ter..** ^The sql
2f450 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
2f460 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 P) routine retur
2f470 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 ns 0 if the prev
2f480 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 ious call to.**
2f490 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 [sqlite3_step](P
2f4a0 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 ) returned [SQLI
2f4b0 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 TE_DONE]. ^The
2f4c0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
2f4d0 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 nt(P).** will re
2f4e0 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 turn non-zero if
2f4f0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
2f500 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d o [sqlite3_step]
2f510 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 (P) returned.**
2f520 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 [SQLITE_ROW], ex
2f530 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 cept in the case
2f540 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 of the [PRAGMA
2f550 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 incremental_vacu
2f560 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 um].** where it
2f570 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a always returns z
2f580 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 ero since each s
2f590 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 tep of that mult
2f5a0 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 i-step.** pragma
2f5b0 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d returns 0 colum
2f5c0 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a ns of data..**.*
2f5d0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
2f5e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e ite3_column_coun
2f5f0 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 t()].*/.SQLITE_A
2f600 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2f610 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 64 61 DCALL sqlite3_da
2f620 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 ta_count(sqlite3
2f630 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
2f640 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2f650 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 Fundamental Data
2f660 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 types.** KEYWORD
2f670 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a S: SQLITE_TEXT.*
2f680 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c *.** ^(Every val
2f690 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 ue in SQLite has
2f6a0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e one of five fun
2f6b0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 damental datatyp
2f6c0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a es:.**.** <ul>.*
2f6d0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 * <li> 64-bit si
2f6e0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 gned integer.**
2f6f0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 <li> 64-bit IEEE
2f700 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
2f710 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 number.** <li> s
2f720 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c tring.** <li> BL
2f730 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a OB.** <li> NULL.
2f740 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a ** </ul>)^.**.**
2f750 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
2f760 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 are codes for e
2f770 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 ach of those typ
2f780 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 es..**.** Note t
2f790 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 hat the SQLITE_T
2f7a0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 EXT constant was
2f7b0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 also used in SQ
2f7c0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a Lite version 2.*
2f7d0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 * for a complete
2f7e0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 ly different mea
2f7f0 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 ning. Software
2f800 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e that links again
2f810 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 st both.** SQLit
2f820 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 e version 2 and
2f830 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
2f840 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 should use SQLI
2f850 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a TE3_TEXT, not.**
2f860 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f SQLITE_TEXT..*/
2f870 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2f880 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 INTEGER 1.#defi
2f890 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 ne SQLITE_FLOAT
2f8a0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
2f8b0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 ITE_BLOB 4.#
2f8c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 define SQLITE_NU
2f8d0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 LL 5.#ifdef
2f8e0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e SQLITE_TEXT.# un
2f8f0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a def SQLITE_TEXT.
2f900 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 #else.# define S
2f910 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 QLITE_TEXT 3
2f920 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 .#endif.#define
2f930 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 SQLITE3_TEXT
2f940 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 3../*.** CAPI3R
2f950 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 EF: Result Value
2f960 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a s From A Query.*
2f970 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c * KEYWORDS: {col
2f980 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
2f990 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a ions}.** METHOD:
2f9a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2f9b0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
2f9c0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 nes return infor
2f9d0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 mation about a s
2f9e0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 ingle column of
2f9f0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 the current.** r
2fa00 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 esult row of a q
2fa10 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 uery. ^In every
2fa20 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 case the first
2fa30 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
2fa40 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 inter.** to the
2fa50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2fa60 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 ent] that is bei
2fa70 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 ng evaluated (th
2fa80 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a e [sqlite3_stmt*
2fa90 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 ].** that was re
2faa0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c turned from [sql
2fab0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2fac0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 )] or one of its
2fad0 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e variants).** an
2fae0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 d the second arg
2faf0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 ument is the ind
2fb00 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e ex of the column
2fb10 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 for which infor
2fb20 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 mation.** should
2fb30 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 be returned. ^T
2fb40 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 he leftmost colu
2fb50 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 mn of the result
2fb60 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 set has the ind
2fb70 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 ex 0..** ^The nu
2fb80 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
2fb90 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 in the result ca
2fba0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 n be determined
2fbb0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
2fbc0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 3_column_count()
2fbd0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 ]..**.** If the
2fbe0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f SQL statement do
2fbf0 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 es not currently
2fc00 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 point to a vali
2fc10 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 d row, or if the
2fc20 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 .** column index
2fc30 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
2fc40 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 , the result is
2fc50 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 undefined..** Th
2fc60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 ese routines may
2fc70 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 only be called
2fc80 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 when the most re
2fc90 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 cent call to.**
2fca0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2fcb0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 has returned [S
2fcc0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e QLITE_ROW] and n
2fcd0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 either.** [sqlit
2fce0 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 e3_reset()] nor
2fcf0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2fd00 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 e()] have been c
2fd10 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 alled subsequent
2fd20 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 ly..** If any of
2fd30 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
2fd40 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 are called after
2fd50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2fd60 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
2fd70 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
2fd80 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f after [sqlite3_
2fd90 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 step()] has retu
2fda0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e rned.** somethin
2fdb0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 g other than [SQ
2fdc0 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 LITE_ROW], the r
2fdd0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 esults are undef
2fde0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c ined..** If [sql
2fdf0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 ite3_step()] or
2fe00 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2fe10 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 ] or [sqlite3_fi
2fe20 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 nalize()].** are
2fe30 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 called from a d
2fe40 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 ifferent thread
2fe50 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 while any of the
2fe60 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 se routines.** a
2fe70 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e re pending, then
2fe80 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
2fe90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
2fea0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
2feb0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 olumn_type() rou
2fec0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
2fed0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 .** [SQLITE_INTE
2fee0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 GER | datatype c
2fef0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 ode] for the ini
2ff00 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a tial data type.*
2ff10 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 * of the result
2ff20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 column. ^The re
2ff30 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 turned value is
2ff40 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 one of [SQLITE_I
2ff50 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c NTEGER],.** [SQL
2ff60 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c ITE_FLOAT], [SQL
2ff70 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 ITE_TEXT], [SQLI
2ff80 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 TE_BLOB], or [SQ
2ff90 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 LITE_NULL]. The
2ffa0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
2ffb0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
2ffc0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f lumn_type() is o
2ffd0 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 nly meaningful i
2ffe0 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e f no type.** con
2fff0 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 versions have oc
30000 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 curred as descri
30010 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 bed below. Afte
30020 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 r a type convers
30030 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 ion,.** the valu
30040 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 e returned by sq
30050 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
30060 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 e() is undefined
30070 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 . Future.** ver
30080 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
30090 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 may change the b
300a0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 ehavior of sqlit
300b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
300c0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 .** following a
300d0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e type conversion.
300e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 .**.** ^If the r
300f0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 esult is a BLOB
30100 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 or UTF-8 string
30110 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
30120 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a _column_bytes().
30130 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
30140 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
30150 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 bytes in that B
30160 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
30170 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
30180 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 is a UTF-16 str
30190 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ing, then sqlite
301a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
301b0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 converts.** the
301c0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 string to UTF-8
301d0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e and then return
301e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
301f0 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 bytes..** ^If th
30200 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 e result is a nu
30210 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e meric value then
30220 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30230 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 bytes() uses.**
30240 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
30250 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 f()] to convert
30260 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 that value to a
30270 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 UTF-8 string and
30280 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 returns.** the
30290 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
302a0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a in that string..
302b0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
302c0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 t is NULL, then
302d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
302e0 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a ytes() returns z
302f0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ero..**.** ^If t
30300 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 he result is a B
30310 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 LOB or UTF-16 st
30320 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 ring then the sq
30330 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
30340 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e es16().** routin
30350 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
30360 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
30370 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 that BLOB or st
30380 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ring..** ^If the
30390 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 result is a UTF
303a0 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 -8 string, then
303b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
303c0 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 ytes16() convert
303d0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 s.** the string
303e0 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 to UTF-16 and th
303f0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e en returns the n
30400 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a umber of bytes..
30410 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
30420 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
30430 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
30440 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
30450 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 () uses.** [sqli
30460 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
30470 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 to convert that
30480 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 value to a UTF-1
30490 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 6 string and ret
304a0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 urns.** the numb
304b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
304c0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e hat string..** ^
304d0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
304e0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 NULL, then sqli
304f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
30500 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 16() returns zer
30510 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 o..**.** ^The va
30520 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 lues returned by
30530 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
30540 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a _bytes()] and .*
30550 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
30560 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 n_bytes16()] do
30570 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 not include the
30580 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 zero terminators
30590 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f at the end.** o
305a0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e f the string. ^
305b0 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 For clarity: the
305c0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 values returned
305d0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
305e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 column_bytes()]
305f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c and [sqlite3_col
30600 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 umn_bytes16()] a
30610 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 re the number of
30620 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 .** bytes in the
30630 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 string, not the
30640 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
30650 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 cters..**.** ^St
30660 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 rings returned b
30670 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
30680 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 _text() and sqli
30690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
306a0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 6(),.** even emp
306b0 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 ty strings, are
306c0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d always zero-term
306d0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 inated. ^The re
306e0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 turn.** value fr
306f0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d om sqlite3_colum
30700 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a n_blob() for a z
30710 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 ero-length BLOB
30720 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
30730 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e r..**.** <b>Warn
30740 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 ing:</b> ^The ob
30750 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 ject returned by
30760 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
30770 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a _value()] is an.
30780 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 ** [unprotected
30790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
307a0 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c bject. In a mul
307b0 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 tithreaded envir
307c0 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e onment,.** an un
307d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
307e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 3_value object m
307f0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 ay only be used
30800 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b safely with.** [
30810 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c sqlite3_bind_val
30820 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ue()] and [sqlit
30830 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
30840 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 )]..** If the [u
30850 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
30860 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
30870 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
30880 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
30890 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 value()] is used
308a0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 in any other wa
308b0 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c y, including cal
308c0 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 ls.** to routine
308d0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f s like [sqlite3_
308e0 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 value_int()], [s
308f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
30900 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c t()],.** or [sql
30910 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
30920 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f ()], the behavio
30930 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 r is not threads
30940 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 afe..**.** These
30950 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 routines attemp
30960 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 t to convert the
30970 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 value where app
30980 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a ropriate. ^For.
30990 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 ** example, if t
309a0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 he internal repr
309b0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c esentation is FL
309c0 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 OAT and a text r
309d0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 esult.** is requ
309e0 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f ested, [sqlite3_
309f0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 snprintf()] is u
30a00 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 sed internally t
30a10 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a o perform the.**
30a20 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f conversion auto
30a30 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 matically. ^(Th
30a40 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c e following tabl
30a50 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f e details the co
30a60 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 nversions.** tha
30a70 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a t are applied:.*
30a80 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
30a90 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 >.** <table bord
30aa0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c er="1">.** <tr><
30ab0 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e th> Internal<br>
30ac0 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 Type <th> Reques
30ad0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e ted<br>Type <th>
30ae0 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a Conversion.**.
30af0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
30b00 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 L <td> INTEGE
30b10 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 R <td> Result
30b20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e is 0.** <tr><td>
30b30 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
30b40 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 FLOAT <td> Re
30b50 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c sult is 0.0.** <
30b60 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
30b70 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
30b80 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 <td> Result is a
30b90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
30ba0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
30bb0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
30bc0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
30bd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
30be0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 ** <tr><td> INTE
30bf0 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 GER <td> FLOAT
30c00 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 <td> Convert
30c10 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f from integer to
30c20 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 float.** <tr><t
30c30 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e d> INTEGER <td>
30c40 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
30c50 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 ASCII rendering
30c60 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a of the integer.*
30c70 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
30c80 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 ER <td> BLOB
30c90 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 <td> Same as
30ca0 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a INTEGER->TEXT.**
30cb0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
30cc0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
30cd0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f <td> [CAST] to
30ce0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e INTEGER.** <tr>
30cf0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 <td> FLOAT <t
30d00 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
30d10 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e > ASCII renderin
30d20 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a g of the float.*
30d30 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 * <tr><td> FLOA
30d40 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 T <td> BLOB
30d50 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 <td> [CAST] t
30d60 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 o BLOB.** <tr><t
30d70 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
30d80 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
30d90 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 [CAST] to INTEGE
30da0 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 R.** <tr><td> T
30db0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f EXT <td> FLO
30dc0 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 AT <td> [CAST
30dd0 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 ] to REAL.** <tr
30de0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
30df0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
30e00 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 d> No change.**
30e10 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
30e20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
30e30 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 <td> [CAST] to
30e40 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c INTEGER.** <tr><
30e50 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
30e60 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
30e70 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a [CAST] to REAL.
30e80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f ** <tr><td> BLO
30e90 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 B <td> TEXT
30ea0 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a <td> Add a z
30eb0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 ero terminator i
30ec0 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 f needed.** </ta
30ed0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 ble>.** </blockq
30ee0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f uote>)^.**.** No
30ef0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 te that when typ
30f00 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 e conversions oc
30f10 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 cur, pointers re
30f20 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a turned by prior.
30f30 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ** calls to sqli
30f40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
30f50 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ), sqlite3_colum
30f60 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 n_text(), and/or
30f70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
30f80 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 mn_text16() may
30f90 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a be invalidated..
30fa0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 ** Type conversi
30fb0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 ons and pointer
30fc0 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 invalidations mi
30fd0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 ght occur.** in
30fe0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 the following ca
30ff0 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ses:.**.** <ul>.
31000 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 ** <li> The init
31010 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 ial content is a
31020 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 BLOB and sqlite
31030 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
31040 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
31050 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
31060 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 () is called. A
31070 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 zero-terminator
31080 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e might.** n
31090 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 eed to be added
310a0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f to the string.</
310b0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 li>.** <li> The
310c0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
310d0 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e is UTF-8 text an
310e0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
310f0 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a _bytes16() or.**
31100 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
31110 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 lumn_text16() is
31120 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f called. The co
31130 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f ntent must be co
31140 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 nverted.**
31150 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a to UTF-16.</li>.
31160 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 ** <li> The init
31170 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 ial content is U
31180 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 TF-16 text and s
31190 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
311a0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 tes() or.**
311b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
311c0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 text() is called
311d0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d . The content m
311e0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 ust be converted
311f0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d .** to UTF-
31200 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 8.</li>.** </ul>
31210 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 .**.** ^Conversi
31220 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d ons between UTF-
31230 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 16be and UTF-16l
31240 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e e are always don
31250 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 e in place and d
31260 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 o.** not invalid
31270 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e ate a prior poin
31280 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 ter, though of c
31290 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e ourse the conten
312a0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a t of the buffer.
312b0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f ** that the prio
312c0 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 r pointer refere
312d0 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 nces will have b
312e0 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f een modified. O
312f0 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 ther kinds.** of
31300 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 conversion are
31310 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 done in place wh
31320 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c en it is possibl
31330 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 e, but sometimes
31340 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 they.** are not
31350 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e possible and in
31360 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 those cases pri
31370 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 or pointers are
31380 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a invalidated..**.
31390 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f ** The safest po
313a0 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b licy is to invok
313b0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 e these routines
313c0 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 .** in one of th
313d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 e following ways
313e0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
313f0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
31400 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f umn_text() follo
31410 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 wed by sqlite3_c
31420 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c olumn_bytes()</l
31430 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 i>.** <li>sqlit
31440 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
31450 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
31460 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
31470 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 s()</li>.** <li
31480 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
31490 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 text16() followe
314a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
314b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c umn_bytes16()</l
314c0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a i>.** </ul>.**.*
314d0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
314e0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c , you should cal
314f0 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e l sqlite3_column
31500 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 _text(),.** sqli
31510 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
31520 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f ), or sqlite3_co
31530 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 lumn_text16() fi
31540 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 rst to force the
31550 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 result.** into
31560 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d the desired form
31570 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 at, then invoke
31580 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
31590 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c ytes() or.** sql
315a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
315b0 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 s16() to find th
315c0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 e size of the re
315d0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 sult. Do not mi
315e0 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 x calls.** to sq
315f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
31600 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 t() or sqlite3_c
31610 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 olumn_blob() wit
31620 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 h calls to.** sq
31630 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
31640 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e es16(), and do n
31650 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 ot mix calls to
31660 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
31670 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 ext16().** with
31680 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
31690 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e _column_bytes().
316a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e .**.** ^The poin
316b0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 ters returned ar
316c0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 e valid until a
316d0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 type conversion
316e0 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 occurs as.** des
316f0 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 cribed above, or
31700 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f until [sqlite3_
31710 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 step()] or [sqli
31720 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a te3_reset()] or.
31730 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ** [sqlite3_fina
31740 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 lize()] is calle
31750 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 d. ^The memory
31760 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f space used to ho
31770 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e ld strings.** an
31780 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 d BLOBs is freed
31790 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
317a0 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e Do <em>not</em>
317b0 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 pass the pointe
317c0 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 rs returned.** f
317d0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c rom [sqlite3_col
317e0 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 umn_blob()], [sq
317f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
31800 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a t()], etc. into.
31810 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
31820 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 ()]..**.** ^(If
31830 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
31840 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ion error occurs
31850 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c during the eval
31860 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a uation of any.**
31870 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
31880 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 es, a default va
31890 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e lue is returned.
318a0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 The default va
318b0 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 lue.** is either
318c0 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 the integer 0,
318d0 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 the floating poi
318e0 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f nt number 0.0, o
318f0 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e r a NULL.** poin
31900 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 ter. Subsequent
31910 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
31920 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 e3_errcode()] wi
31930 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 ll return.** [SQ
31940 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a LITE_NOMEM].)^.*
31950 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
31960 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f st void *SQLITE_
31970 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
31980 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 column_blob(sqli
31990 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
319a0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
319b0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
319c0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ALL sqlite3_colu
319d0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 mn_bytes(sqlite3
319e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
319f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
31a00 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
31a10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
31a20 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f bytes16(sqlite3_
31a30 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
31a40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 ;.SQLITE_API dou
31a50 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 ble SQLITE_STDCA
31a60 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
31a70 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 n_double(sqlite3
31a80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
31a90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
31aa0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
31ab0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
31ac0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 int(sqlite3_stmt
31ad0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
31ae0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
31af0 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 _int64 SQLITE_ST
31b00 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f DCALL sqlite3_co
31b10 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 lumn_int64(sqlit
31b20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
31b30 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
31b40 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 const unsigned c
31b50 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 har *SQLITE_STDC
31b60 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ALL sqlite3_colu
31b70 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f mn_text(sqlite3_
31b80 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
31b90 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
31ba0 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f st void *SQLITE_
31bb0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
31bc0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 column_text16(sq
31bd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
31be0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
31bf0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
31c00 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f DCALL sqlite3_co
31c10 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 lumn_type(sqlite
31c20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
31c30 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 l);.SQLITE_API s
31c40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 53 51 qlite3_value *SQ
31c50 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
31c60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
31c70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
31c80 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a int iCol);../*.
31c90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 ** CAPI3REF: Des
31ca0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 troy A Prepared
31cb0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
31cc0 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 .** DESTRUCTOR:
31cd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
31ce0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
31cf0 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 finalize() funct
31d00 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f ion is called to
31d10 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 delete a [prepa
31d20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
31d30 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
31d40 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f recent evaluatio
31d50 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 n of the stateme
31d60 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e nt encountered n
31d70 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 o errors.** or i
31d80 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
31d90 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 is never been ev
31da0 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 aluated, then sq
31db0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
31dc0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 returns.** SQLI
31dd0 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 TE_OK. ^If the
31de0 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c most recent eval
31df0 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d uation of statem
31e00 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 ent S failed, th
31e10 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 en.** sqlite3_fi
31e20 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e nalize(S) return
31e30 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 s the appropriat
31e40 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f e [error code] o
31e50 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 r.** [extended e
31e60 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a rror code]..**.*
31e70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 * ^The sqlite3_f
31e80 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 inalize(S) routi
31e90 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 ne can be called
31ea0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 at any point du
31eb0 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 ring.** the life
31ec0 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 cycle of [prepa
31ed0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
31ee0 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 :.** before stat
31ef0 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 ement S is ever
31f00 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 evaluated, after
31f10 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 .** one or more
31f20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
31f30 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 3_reset()], or a
31f40 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a fter any call.**
31f50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
31f60 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 p()] regardless
31f70 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
31f80 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 t the statement
31f90 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 has.** completed
31fa0 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a execution..**.*
31fb0 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 * ^Invoking sqli
31fc0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f te3_finalize() o
31fd0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 n a NULL pointer
31fe0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e is a harmless n
31ff0 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 o-op..**.** The
32000 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
32010 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 finalize every
32020 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
32030 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f ent] in order to
32040 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 avoid.** resour
32050 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 ce leaks. It is
32060 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f a grievous erro
32070 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 r for the applic
32080 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 ation to try to
32090 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 use.** a prepare
320a0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 d statement afte
320b0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 r it has been fi
320c0 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 nalized. Any us
320d0 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a e of a prepared.
320e0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 ** statement aft
320f0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 er it has been f
32100 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 inalized can res
32110 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 ult in undefined
32120 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 and.** undesira
32130 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 ble behavior suc
32140 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 h as segfaults a
32150 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 nd heap corrupti
32160 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 on..*/.SQLITE_AP
32170 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
32180 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 69 6e CALL sqlite3_fin
32190 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 alize(sqlite3_st
321a0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
321b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
321c0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 et A Prepared St
321d0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
321e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
321f0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 3_stmt.**.** The
32200 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 sqlite3_reset()
32210 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c function is cal
32220 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b led to reset a [
32230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
32240 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 nt].** object ba
32250 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
32260 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 l state, ready t
32270 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 o be re-executed
32280 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 ..** ^Any SQL st
32290 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 atement variable
322a0 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 s that had value
322b0 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 s bound to them
322c0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 using.** the [sq
322d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
322e0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a | sqlite3_bind_*
322f0 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 () API] retain t
32300 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 heir values..**
32310 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 Use [sqlite3_cle
32320 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 ar_bindings()] t
32330 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 o reset the bind
32340 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ings..**.** ^The
32350 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
32360 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 S)] interface re
32370 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 sets the [prepar
32380 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a ed statement] S.
32390 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 ** back to the b
323a0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 eginning of its
323b0 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e program..**.** ^
323c0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
323d0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
323e0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
323f0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
32400 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 d statement] S r
32410 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
32420 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f ROW] or [SQLITE_
32430 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 DONE],.** or if
32440 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
32450 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f ] has never befo
32460 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f re been called o
32470 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 n S,.** then [sq
32480 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
32490 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
324a0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 OK]..**.** ^If t
324b0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 he most recent c
324c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
324d0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 step(S)] for the
324e0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
324f0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 atement] S indic
32500 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 ated an error, t
32510 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f hen.** [sqlite3_
32520 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e reset(S)] return
32530 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 s an appropriate
32540 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a [error code]..*
32550 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 *.** ^The [sqlit
32560 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 e3_reset(S)] int
32570 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 erface does not
32580 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
32590 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c s.** of any [sql
325a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 ite3_bind_blob|b
325b0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 indings] on the
325c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
325d0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 ent] S..*/.SQLIT
325e0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
325f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
32600 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 _reset(sqlite3_s
32610 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
32620 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 .** CAPI3REF: Cr
32630 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 eate Or Redefine
32640 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a SQL Functions.*
32650 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e * KEYWORDS: {fun
32660 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 ction creation r
32670 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 outines}.** KEYW
32680 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 ORDS: {applicati
32690 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
326a0 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 unction}.** KEYW
326b0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 ORDS: {applicati
326c0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
326d0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 unctions}.** MET
326e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
326f0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 ** ^These functi
32700 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c ons (collectivel
32710 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 y known as "func
32720 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f tion creation ro
32730 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 utines").** are
32740 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 used to add SQL
32750 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 functions or agg
32760 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 regates or to re
32770 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 define the behav
32780 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 ior.** of existi
32790 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ng SQL functions
327a0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 or aggregates.
327b0 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 The only differ
327c0 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a ences between.**
327d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
327e0 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 are the text enc
327f0 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 oding expected f
32800 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 or.** the second
32810 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 parameter (the
32820 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 name of the func
32830 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 tion being creat
32840 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 ed).** and the p
32850 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e resence or absen
32860 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 ce of a destruct
32870 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a or callback for.
32880 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
32890 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e on data pointer.
328a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
328b0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 t parameter is t
328c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
328d0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 nection] to whic
328e0 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e h the SQL.** fun
328f0 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 ction is to be a
32900 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 dded. ^If an ap
32910 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d plication uses m
32920 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 ore than one dat
32930 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
32940 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 ion then applica
32950 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
32960 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 functions must
32970 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 be added.** to e
32980 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
32990 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 nection separate
329a0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ly..**.** ^The s
329b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
329c0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
329d0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
329e0 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 to be created or
329f0 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 .** redefined.
32a00 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 ^The length of t
32a10 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 he name is limit
32a20 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 ed to 255 bytes
32a30 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 in a UTF-8.** re
32a40 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 presentation, ex
32a50 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a clusive of the z
32a60 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero-terminator.
32a70 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 ^Note that the
32a80 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c name.** length l
32a90 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 imit is in UTF-8
32aa0 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 bytes, not char
32ab0 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 acters nor UTF-1
32ac0 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6 bytes. .** ^A
32ad0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 ny attempt to cr
32ae0 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 eate a function
32af0 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 with a longer na
32b00 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c me.** will resul
32b10 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 t in [SQLITE_MIS
32b20 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 USE] being retur
32b30 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
32b40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
32b50 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 (nArg).** is the
32b60 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d number of argum
32b70 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 ents that the SQ
32b80 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a L function or.**
32b90 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 aggregate takes
32ba0 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d . ^If this param
32bb0 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e eter is -1, then
32bc0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
32bd0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 n or.** aggregat
32be0 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e e may take any n
32bf0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e umber of argumen
32c00 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 ts between 0 and
32c10 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 the limit.** se
32c20 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 t by [sqlite3_li
32c30 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d mit]([SQLITE_LIM
32c40 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d IT_FUNCTION_ARG]
32c50 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 ). If the third
32c60 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 .** parameter is
32c70 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 less than -1 or
32c80 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 greater than 12
32c90 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 7 then the behav
32ca0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 ior is.** undefi
32cb0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
32cc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
32cd0 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 , eTextRep, spec
32ce0 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 ifies what.** [S
32cf0 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 QLITE_UTF8 | tex
32d00 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 t encoding] this
32d10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 SQL function pr
32d20 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 efers for.** its
32d30 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 parameters. Th
32d40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
32d50 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 ould set this pa
32d60 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 rameter to.** [S
32d70 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 QLITE_UTF16LE] i
32d80 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 f the function i
32d90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e mplementation in
32da0 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 vokes .** [sqlit
32db0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c e3_value_text16l
32dc0 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 e()] on an input
32dd0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 , or [SQLITE_UTF
32de0 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 16BE] if the.**
32df0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
32e00 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f nvokes [sqlite3_
32e10 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 value_text16be()
32e20 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f ] on an input, o
32e30 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 r.** [SQLITE_UTF
32e40 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 16] if [sqlite3_
32e50 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 value_text16()]
32e60 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c is used, or [SQL
32e70 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 ITE_UTF8].** oth
32e80 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 erwise. ^The sa
32e90 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 me SQL function
32ea0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 may be registere
32eb0 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 d multiple times
32ec0 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 using.** differ
32ed0 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65 ent preferred te
32ee0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 xt encodings, wi
32ef0 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 th different imp
32f00 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 lementations for
32f10 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e .** each encodin
32f20 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 g..** ^When mult
32f30 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 iple implementat
32f40 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
32f50 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 function are av
32f60 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a ailable, SQLite.
32f70 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 ** will pick the
32f80 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 one that involv
32f90 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f es the least amo
32fa0 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 unt of data conv
32fb0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ersion..**.** ^T
32fc0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
32fd0 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c ter may optional
32fe0 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 ly be ORed with
32ff0 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e [SQLITE_DETERMIN
33000 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 ISTIC].** to sig
33010 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e nal that the fun
33020 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 ction will alway
33030 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d s return the sam
33040 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a e result given.*
33050 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 * the same input
33060 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c s within a singl
33070 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e e SQL statement.
33080 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 Most SQL funct
33090 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 ions are.** dete
330a0 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 rministic. The
330b0 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d built-in [random
330c0 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ()] SQL function
330d0 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f is an example o
330e0 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 f a.** function
330f0 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 that is not dete
33100 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 rministic. The
33110 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 SQLite query pla
33120 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a nner is able to.
33130 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 ** perform addit
33140 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 ional optimizati
33150 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 ons on determini
33160 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 stic functions,
33170 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 so use.** of the
33180 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 [SQLITE_DETERMI
33190 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 NISTIC] flag is
331a0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 recommended wher
331b0 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a e possible..**.*
331c0 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 * ^(The fifth pa
331d0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 rameter is an ar
331e0 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e bitrary pointer.
331f0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 The implementa
33200 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 tion of the.** f
33210 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e unction can gain
33220 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 access to this
33230 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 pointer using [s
33240 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
33250 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ()].)^.**.** ^Th
33260 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 e sixth, seventh
33270 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 and eighth para
33280 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 meters, xFunc, x
33290 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c Step and xFinal,
332a0 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 are.** pointers
332b0 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 to C-language f
332c0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d unctions that im
332d0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 plement the SQL
332e0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 function or.** a
332f0 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 ggregate. ^A sca
33300 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e lar SQL function
33310 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 requires an imp
33320 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
33330 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c he xFunc.** call
33340 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 back only; NULL
33350 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 pointers must be
33360 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 passed as the x
33370 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a Step and xFinal.
33380 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e ** parameters. ^
33390 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c An aggregate SQL
333a0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
333b0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 es an implementa
333c0 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a tion of xStep.**
333d0 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 and xFinal and
333e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 NULL pointer mus
333f0 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 t be passed for
33400 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 xFunc. ^To delet
33410 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a e an existing.**
33420 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
33430 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 aggregate, pass
33440 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 NULL pointers f
33450 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e or all three fun
33460 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 ction.** callbac
33470 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 ks..**.** ^(If t
33480 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 he ninth paramet
33490 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 er to sqlite3_cr
334a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 eate_function_v2
334b0 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a () is not NULL,.
334c0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 ** then it is de
334d0 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 structor for the
334e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
334f0 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 a pointer. .** T
33500 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 he destructor is
33510 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 invoked when th
33520 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 e function is de
33530 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 leted, either by
33540 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f being.** overlo
33550 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 aded or when the
33560 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
33570 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a tion closes.)^.*
33580 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f * ^The destructo
33590 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 r is also invoke
335a0 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f d if the call to
335b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 .** sqlite3_crea
335c0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 te_function_v2()
335d0 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e fails..** ^When
335e0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
335f0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 callback of the
33600 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 tenth parameter
33610 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a is invoked, it.*
33620 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 * is passed a si
33630 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
33640 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ich is a copy of
33650 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
33660 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 data .** pointe
33670 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 r which was the
33680 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 fifth parameter
33690 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 to sqlite3_creat
336a0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e e_function_v2().
336b0 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 .**.** ^It is pe
336c0 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 rmitted to regis
336d0 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 ter multiple imp
336e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
336f0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 the same.** func
33700 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 tions with the s
33710 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 ame name but wit
33720 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 h either differi
33730 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a ng numbers of.**
33740 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 arguments or di
33750 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 ffering preferre
33760 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 d text encodings
33770 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 . ^SQLite will
33780 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 use.** the imple
33790 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d mentation that m
337a0 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 ost closely matc
337b0 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 hes the way in w
337c0 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 hich the.** SQL
337d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 function is used
337e0 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 . ^A function i
337f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
33800 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 th a non-negativ
33810 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 e.** nArg parame
33820 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 ter is a better
33830 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e match than a fun
33840 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
33850 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e tion with.** a n
33860 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e egative nArg. ^
33870 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 A function where
33880 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 the preferred t
33890 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 ext encoding.**
338a0 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 matches the data
338b0 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 base encoding is
338c0 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 a better.** mat
338d0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 ch than a functi
338e0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 on where the enc
338f0 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 oding is differe
33900 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 nt. .** ^A func
33910 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 tion where the e
33920 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e ncoding differen
33930 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 ce is between UT
33940 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 F16le and UTF16b
33950 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 e.** is a closer
33960 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 match than a fu
33970 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
33980 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 encoding differ
33990 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 ence is.** betwe
339a0 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 en UTF8 and UTF1
339b0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 6..**.** ^Built-
339c0 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 in functions may
339d0 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 be overloaded b
339e0 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f y new applicatio
339f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
33a00 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 ons..**.** ^An a
33a10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
33a20 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 ed function is p
33a30 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c ermitted to call
33a40 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 other.** SQLite
33a50 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f interfaces. Ho
33a60 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c wever, such call
33a70 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c s must not.** cl
33a80 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ose the database
33a90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 connection nor
33aa0 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 finalize or rese
33ab0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a t the prepared.*
33ac0 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 * statement in w
33ad0 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f hich the functio
33ae0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f n is running..*/
33af0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
33b00 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
33b10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
33b20 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 nction(. sqlite
33b30 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 3 *db,. const c
33b40 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 har *zFunctionNa
33b50 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
33b60 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
33b70 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
33b80 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
33b90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
33ba0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
33bb0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
33bc0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
33bd0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
33be0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
33bf0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
33c00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 ite3_context*).)
33c10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
33c20 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
33c30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
33c40 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c unction16(. sql
33c50 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
33c60 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f t void *zFunctio
33c70 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
33c80 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
33c90 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
33ca0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
33cb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
33cc0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
33cd0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
33ce0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
33cf0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
33d00 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
33d10 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
33d20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
33d30 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ).);.SQLITE_API
33d40 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
33d50 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 LL sqlite3_creat
33d60 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 e_function_v2(.
33d70 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 sqlite3 *db,.
33d80 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e const char *zFun
33d90 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 ctionName,. int
33da0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 nArg,. int eTe
33db0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 xtRep,. void *p
33dc0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 App,. void (*xF
33dd0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
33de0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
33df0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
33e00 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
33e10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
33e20 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
33e30 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
33e40 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
33e50 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 ext*),. void(*x
33e60 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a Destroy)(void*).
33e70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
33e80 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e EF: Text Encodin
33e90 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 gs.**.** These c
33ea0 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 onstant define i
33eb0 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 nteger codes tha
33ec0 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 t represent the
33ed0 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 various.** text
33ee0 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 encodings suppor
33ef0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a ted by SQLite..*
33f00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
33f10 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 _UTF8
33f20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 1 /* IMP: R-3
33f30 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 7514-35566 */.#d
33f40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
33f50 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 16LE 2
33f60 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 /* IMP: R-03371
33f70 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e -37637 */.#defin
33f80 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 e SQLITE_UTF16BE
33f90 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 3 /*
33fa0 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 IMP: R-51971-341
33fb0 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 54 */.#define SQ
33fc0 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 LITE_UTF16
33fd0 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 4 /* Use
33fe0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
33ff0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
34000 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 ITE_ANY
34010 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 5 /* Depre
34020 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 cated */.#define
34030 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c SQLITE_UTF16_AL
34040 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 IGNED 8 /* s
34050 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
34060 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a llation only */.
34070 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
34080 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a Function Flags.
34090 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
340a0 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 tants may be ORe
340b0 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 d together with
340c0 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the .** [SQLITE_
340d0 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 UTF8 | preferred
340e0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 text encoding]
340f0 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 as the fourth ar
34100 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 gument.** to [sq
34110 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
34120 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 ction()], [sqlit
34130 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
34140 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b on16()], or.** [
34150 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
34160 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a unction_v2()]..*
34170 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
34180 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 _DETERMINISTIC
34190 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 0x800../*.** C
341a0 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 API3REF: Depreca
341b0 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a ted Functions.**
341c0 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a DEPRECATED.**.*
341d0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
341e0 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 s are [deprecate
341f0 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f d]. In order to
34200 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 maintain.** bac
34210 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
34220 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 lity with older
34230 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 code, these func
34240 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a tions continue .
34250 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ** to be support
34260 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 ed. However, ne
34270 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 w applications s
34280 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 hould avoid.** t
34290 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 he use of these
342a0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 functions. To e
342b0 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d ncourage program
342c0 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a mers to avoid.**
342d0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
342e0 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 , we will not ex
342f0 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79 20 plain what they
34300 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 do..*/.#ifndef S
34310 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 QLITE_OMIT_DEPRE
34320 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 CATED.SQLITE_API
34330 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 SQLITE_DEPRECAT
34340 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 ED int SQLITE_ST
34350 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67 DCALL sqlite3_ag
34360 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 gregate_count(sq
34370 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
34380 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
34390 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
343a0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
343b0 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 sqlite3_expired
343c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
343d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
343e0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
343f0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
34400 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 sqlite3_transfe
34410 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
34420 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 e3_stmt*, sqlite
34430 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 3_stmt*);.SQLITE
34440 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 _API SQLITE_DEPR
34450 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 ECATED int SQLIT
34460 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
34470 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 3_global_recover
34480 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 (void);.SQLITE_A
34490 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 PI SQLITE_DEPREC
344a0 41 54 45 44 20 76 6f 69 64 20 53 51 4c 49 54 45 ATED void SQLITE
344b0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
344c0 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 _thread_cleanup(
344d0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 void);.SQLITE_AP
344e0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 I SQLITE_DEPRECA
344f0 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 TED int SQLITE_S
34500 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d TDCALL sqlite3_m
34510 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 emory_alarm(void
34520 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
34530 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 3_int64,int),.
34540 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
34550 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 void*,sqlite
34560 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 3_int64);.#endif
34570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
34580 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 : Obtaining SQL
34590 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 Values.** METHOD
345a0 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a : sqlite3_value.
345b0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 **.** The C-lang
345c0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 uage implementat
345d0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 ion of SQL funct
345e0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
345f0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 tes uses.** this
34600 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 set of interfac
34610 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 e routines to ac
34620 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 cess the paramet
34630 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 er values on.**
34640 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 the function or
34650 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a aggregate. .**.
34660 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f ** The xFunc (fo
34670 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f r scalar functio
34680 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f ns) or xStep (fo
34690 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 r aggregates) pa
346a0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b rameters.** to [
346b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
346c0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b unction()] and [
346d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
346e0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 unction16()].**
346f0 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 define callbacks
34700 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 that implement
34710 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
34720 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 s and aggregates
34730 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 ..** The 3rd par
34740 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 ameter to these
34750 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 callbacks is an
34760 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 array of pointer
34770 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 s to.** [protect
34780 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
34790 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 ] objects. Ther
347a0 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 e is one [sqlite
347b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
347c0 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 for.** each para
347d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c meter to the SQL
347e0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 function. Thes
347f0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 e routines are u
34800 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 sed to.** extrac
34810 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 t values from th
34820 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
34830 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a ] objects..**.**
34840 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
34850 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b work only with [
34860 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
34870 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
34880 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 ..** Any attempt
34890 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f to use these ro
348a0 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e utines on an [un
348b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
348c0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 3_value].** obje
348d0 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e ct results in un
348e0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 defined behavior
348f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 ..**.** ^These r
34900 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 outines work jus
34910 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 t like the corre
34920 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e sponding [column
34930 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
34940 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 s].** except tha
34950 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 t these routines
34960 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b take a single [
34970 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
34980 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 3_value] object.
34990 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 ** pointer inste
349a0 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 ad of a [sqlite3
349b0 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 _stmt*] pointer
349c0 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 and an integer c
349d0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a olumn number..**
349e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
349f0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 _value_text16()
34a00 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 interface extrac
34a10 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 ts a UTF-16 stri
34a20 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 ng.** in the nat
34a30 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f ive byte-order o
34a40 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 f the host machi
34a50 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c ne. ^The.** sql
34a60 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
34a70 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 6be() and sqlite
34a80 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 3_value_text16le
34a90 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
34aa0 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 extract UTF-16
34ab0 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 strings as big-e
34ac0 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 ndian and little
34ad0 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 -endian respecti
34ae0 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 vely..**.** ^(Th
34af0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
34b00 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 numeric_type() i
34b10 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 nterface attempt
34b20 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 s to apply.** nu
34b30 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 meric affinity t
34b40 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 o the value. Th
34b50 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e is means that an
34b60 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d attempt is.** m
34b70 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 ade to convert t
34b80 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 he value to an i
34b90 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 nteger or floati
34ba0 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a ng point. If.**
34bb0 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 such a conversi
34bc0 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 on is possible w
34bd0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 ithout loss of i
34be0 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f nformation (in o
34bf0 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 ther.** words, i
34c00 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 f the value is a
34c10 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f string that loo
34c20 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 ks like a number
34c30 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f ).** then the co
34c40 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 nversion is perf
34c50 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 ormed. Otherwis
34c60 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 e no conversion
34c70 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b occurs..** The [
34c80 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c SQLITE_INTEGER |
34c90 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 datatype] after
34ca0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 conversion is r
34cb0 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a eturned.)^.**.**
34cc0 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 Please pay part
34cd0 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e icular attention
34ce0 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 to the fact tha
34cf0 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 t the pointer re
34d00 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b turned.** from [
34d10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
34d20 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ob()], [sqlite3_
34d30 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f value_text()], o
34d40 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 r.** [sqlite3_va
34d50 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 lue_text16()] ca
34d60 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 n be invalidated
34d70 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 by a subsequent
34d80 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
34d90 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
34da0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 ()], [sqlite3_va
34db0 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 lue_bytes16()],
34dc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
34dd0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 ext()],.** or [s
34de0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
34df0 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 t16()]..**.** Th
34e00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 ese routines mus
34e10 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
34e20 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
34e30 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 as.** the SQL f
34e40 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 unction that sup
34e50 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 plied the [sqlit
34e60 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d e3_value*] param
34e70 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 eters..*/.SQLITE
34e80 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
34e90 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
34ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
34eb0 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ob(sqlite3_value
34ec0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
34ed0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
34ee0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f L sqlite3_value_
34ef0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 bytes(sqlite3_va
34f00 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
34f10 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
34f20 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c CALL sqlite3_val
34f30 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 ue_bytes16(sqlit
34f40 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
34f50 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 53 51 TE_API double SQ
34f60 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
34f70 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c ite3_value_doubl
34f80 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
34f90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
34fa0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
34fb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 sqlite3_value_i
34fc0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt(sqlite3_value
34fd0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 *);.SQLITE_API s
34fe0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c qlite3_int64 SQL
34ff0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
35000 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 te3_value_int64(
35010 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
35020 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
35030 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 t unsigned char
35040 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
35050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
35060 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 xt(sqlite3_value
35070 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 *);.SQLITE_API c
35080 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 onst void *SQLIT
35090 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
350a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 3_value_text16(s
350b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
350c0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
350d0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
350e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 DCALL sqlite3_va
350f0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c lue_text16le(sql
35100 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
35110 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
35120 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 oid *SQLITE_STDC
35130 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ALL sqlite3_valu
35140 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 e_text16be(sqlit
35150 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
35160 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
35170 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
35180 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 3_value_type(sql
35190 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
351a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
351b0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
351c0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 te3_value_numeri
351d0 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 c_type(sqlite3_v
351e0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 alue*);../*.** C
351f0 41 50 49 33 52 45 46 3a 20 46 69 6e 64 69 6e 67 API3REF: Finding
35200 20 54 68 65 20 53 75 62 74 79 70 65 20 4f 66 20 The Subtype Of
35210 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 SQL Values.** ME
35220 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 THOD: sqlite3_va
35230 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 lue.**.** The sq
35240 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 lite3_value_subt
35250 79 70 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20 ype(V) function
35260 72 65 74 75 72 6e 73 20 74 68 65 20 73 75 62 74 returns the subt
35270 79 70 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 ype for.** an [a
35280 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
35290 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d ed SQL function]
352a0 20 61 72 67 75 6d 65 6e 74 20 56 2e 20 20 54 68 argument V. Th
352b0 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66 e subtype.** inf
352c0 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 ormation can be
352d0 75 73 65 64 20 74 6f 20 70 61 73 73 20 61 20 6c used to pass a l
352e0 69 6d 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66 imited amount of
352f0 20 63 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a context from.**
35300 20 6f 6e 65 20 53 51 4c 20 66 75 6e 63 74 69 6f one SQL functio
35310 6e 20 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55 n to another. U
35320 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f se the [sqlite3_
35330 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65 28 29 result_subtype()
35340 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 ].** routine to
35350 73 65 74 20 74 68 65 20 73 75 62 74 79 70 65 20 set the subtype
35360 66 6f 72 20 74 68 65 20 72 65 74 75 72 6e 20 76 for the return v
35370 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 66 alue of an SQL f
35380 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 unction..**.** S
35390 51 4c 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75 QLite makes no u
353a0 73 65 20 6f 66 20 73 75 62 74 79 70 65 20 69 74 se of subtype it
353b0 73 65 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c 79 self. It merely
353c0 20 70 61 73 73 65 73 20 74 68 65 20 73 75 62 74 passes the subt
353d0 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 ype.** from the
353e0 72 65 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 result of one [a
353f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
35400 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d ed SQL function]
35410 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 into the.** inp
35420 75 74 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a ut of another..*
35430 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 75 6e 73 /.SQLITE_API uns
35440 69 67 6e 65 64 20 69 6e 74 20 53 51 4c 49 54 45 igned int SQLITE
35450 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
35460 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73 _value_subtype(s
35470 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
35480 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
35490 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53 Copy And Free S
354a0 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 QL Values.** MET
354b0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c HOD: sqlite3_val
354c0 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ue.**.** ^The sq
354d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 lite3_value_dup(
354e0 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b V) interface mak
354f0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 es a copy of the
35500 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
35510 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 .** object D and
35520 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
35530 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e er to that copy.
35540 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ^The [sqlite3_
35550 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a value] returned.
35560 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74 ** is a [protect
35570 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
35580 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66 ] object even if
35590 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f the input is no
355a0 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 t..** ^The sqlit
355b0 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 e3_value_dup(V)
355c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
355d0 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e s NULL if V is N
355e0 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d ULL or if a.** m
355f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
35600 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 fails..**.** ^T
35610 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
35620 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61 _free(V) interfa
35630 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c ce frees an [sql
35640 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
35650 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 ct.** previously
35660 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
35670 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 sqlite3_value_du
35680 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 p()]. ^If V is
35690 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
356a0 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 * then sqlite3_v
356b0 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20 alue_free(V) is
356c0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 a harmless no-op
356d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
356e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 53 sqlite3_value *S
356f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
35700 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 lite3_value_dup(
35710 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 const sqlite3_va
35720 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
35730 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 I void SQLITE_ST
35740 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 DCALL sqlite3_va
35750 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33 lue_free(sqlite3
35760 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _value*);../*.**
35770 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 CAPI3REF: Obtai
35780 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 n Aggregate Func
35790 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 tion Context.**
357a0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
357b0 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d context.**.** Im
357c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
357d0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 aggregate SQL f
357e0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 unctions use thi
357f0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 s.** routine to
35800 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
35810 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 for storing thei
35820 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e r state..**.** ^
35830 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 The first time t
35840 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 he sqlite3_aggre
35850 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e gate_context(C,N
35860 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c ) routine is cal
35870 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 led .** for a pa
35880 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 rticular aggrega
35890 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c te function, SQL
358a0 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 ite.** allocates
358b0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 N of memory, ze
358c0 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 roes out that me
358d0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e mory, and return
358e0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 s a pointer.** t
358f0 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 o the new memory
35900 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 . ^On second and
35910 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
35920 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f s to.** sqlite3_
35930 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
35940 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 t() for the same
35950 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
35960 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a ion instance,.**
35970 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 the same buffer
35980 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 is returned. S
35990 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
359a0 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f _context() is no
359b0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 rmally.** called
359c0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 once for each i
359d0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 nvocation of the
359e0 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 xStep callback
359f0 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 and then one.**
35a00 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 last time when t
35a10 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 he xFinal callba
35a20 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 ck is invoked.
35a30 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d ^(When no rows m
35a40 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 atch.** an aggre
35a50 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 gate query, the
35a60 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b xStep() callback
35a70 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 of the aggregat
35a80 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d e function.** im
35a90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
35aa0 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 never called and
35ab0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c xFinal() is cal
35ac0 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 led exactly once
35ad0 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 ..** In those ca
35ae0 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 ses, sqlite3_agg
35af0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
35b00 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 might be called
35b10 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 for the.** firs
35b20 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 t time from with
35b30 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a in xFinal().)^.*
35b40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
35b50 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
35b60 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 ext(C,N) routine
35b70 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
35b80 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e pointer .** when
35b90 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 first called if
35ba0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 N is less than
35bb0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f or equal to zero
35bc0 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a or if a memory.
35bd0 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f ** allocate erro
35be0 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 r occurs..**.**
35bf0 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 ^(The amount of
35c00 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 space allocated
35c10 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 by sqlite3_aggre
35c20 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e gate_context(C,N
35c30 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e ) is.** determin
35c40 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 ed by the N para
35c50 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 meter on first s
35c60 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 uccessful call.
35c70 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a Changing the.**
35c80 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 value of N in s
35c90 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 ubsequent call t
35ca0 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 o sqlite3_aggreg
35cb0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 ate_context() wi
35cc0 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 thin.** the same
35cd0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
35ce0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c ion instance wil
35cf0 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 l not resize the
35d00 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
35d10 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e ation.)^ Within
35d20 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c the xFinal call
35d30 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 back, it is cust
35d40 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 omary to set.**
35d50 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 N=0 in calls to
35d60 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
35d70 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 e_context(C,N) s
35d80 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f o that no .** po
35d90 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 intless memory a
35da0 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 llocations occur
35db0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ..**.** ^SQLite
35dc0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 automatically fr
35dd0 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 ees the memory a
35de0 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 llocated by .**
35df0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
35e00 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e e_context() when
35e10 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 the aggregate q
35e20 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a uery concludes..
35e30 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
35e40 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 parameter must b
35e50 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a e a copy of the.
35e60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ** [sqlite3_cont
35e70 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 ext | SQL functi
35e80 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 on context] that
35e90 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 is the first pa
35ea0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 rameter.** to th
35eb0 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 e xStep or xFina
35ec0 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 l callback routi
35ed0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ne that implemen
35ee0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 ts the aggregate
35ef0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a .** function..**
35f00 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
35f10 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
35f20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
35f30 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
35f40 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 the aggregate S
35f50 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 QL function is r
35f60 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 unning..*/.SQLIT
35f70 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 E_API void *SQLI
35f80 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
35f90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
35fa0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
35fb0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 text*, int nByte
35fc0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 s);../*.** CAPI3
35fd0 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 REF: User Data F
35fe0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 or Functions.**
35ff0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
36000 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 context.**.** ^T
36010 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f he sqlite3_user_
36020 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 data() interface
36030 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 returns a copy
36040 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 of.** the pointe
36050 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 r that was the p
36060 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 UserData paramet
36070 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 er (the 5th para
36080 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 meter).** of the
36090 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
360a0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 _function()].**
360b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
360c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
360d0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 ] routines that
360e0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 originally.** re
360f0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 gistered the app
36100 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 lication defined
36110 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
36120 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 This routine mu
36130 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f st be called fro
36140 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 m the same threa
36150 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 d in which.** th
36160 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
36170 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 fined function i
36180 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 s running..*/.SQ
36190 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 LITE_API void *S
361a0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
361b0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
361c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
361d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
361e0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
361f0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 nection For Func
36200 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a tions.** METHOD:
36210 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
36220 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
36230 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
36240 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 andle() interfac
36250 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 e returns a copy
36260 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 of.** the point
36270 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 er to the [datab
36280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
36290 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 (the 1st paramet
362a0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 er).** of the [s
362b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
362c0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 nction()].** and
362d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
362e0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 _function16()] r
362f0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 outines that ori
36300 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 ginally.** regis
36310 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 tered the applic
36320 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 ation defined fu
36330 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 nction..*/.SQLIT
36340 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 53 E_API sqlite3 *S
36350 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
36360 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
36370 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f _handle(sqlite3_
36380 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a context*);../*.*
36390 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 * CAPI3REF: Func
363a0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 tion Auxiliary D
363b0 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ata.** METHOD: s
363c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a qlite3_context.*
363d0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
363e0 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 ions may be used
363f0 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 by (non-aggrega
36400 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e te) SQL function
36410 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 s to.** associat
36420 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 e metadata with
36430 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e argument values.
36440 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c If the same val
36450 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a ue is passed to.
36460 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f ** multiple invo
36470 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
36480 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ame SQL function
36490 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 during query ex
364a0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a ecution, under.*
364b0 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 * some circumsta
364c0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 nces the associa
364d0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 ted metadata may
364e0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 be preserved.
364f0 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 An example.** of
36500 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 where this migh
36510 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 t be useful is i
36520 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 n a regular-expr
36530 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a ession matching.
36540 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 ** function. The
36550 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f compiled versio
36560 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 n of the regular
36570 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 expression can
36580 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 be stored as.**
36590 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 metadata associa
365a0 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74 ted with the pat
365b0 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a tern string. .*
365c0 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 * Then as long a
365d0 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 s the pattern st
365e0 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 ring remains the
365f0 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f same,.** the co
36600 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 mpiled regular e
36610 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 xpression can be
36620 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 reused on multi
36630 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f ple.** invocatio
36640 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 ns of the same f
36650 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e unction..**.** ^
36660 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
36670 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 auxdata() interf
36680 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
36690 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 inter to the met
366a0 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 adata.** associa
366b0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 ted by the sqlit
366c0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
366d0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 function with t
366e0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a he Nth argument.
366f0 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 ** value to the
36700 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
36710 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 ned function. ^I
36720 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 f there is no me
36730 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 tadata.** associ
36740 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75 ated with the fu
36750 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c nction argument,
36760 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 this sqlite3_ge
36770 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 t_auxdata() inte
36780 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 rface.** returns
36790 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
367a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
367b0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
367c0 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 C,N,P,X) interfa
367d0 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 ce saves P as me
367e0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e tadata for the N
367f0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 -th.** argument
36800 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
36810 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
36820 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e ion. ^Subsequen
36830 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 t.** calls to sq
36840 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
36850 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 a(C,N) return P
36860 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 from the most re
36870 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cent.** sqlite3_
36880 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c set_auxdata(C,N,
36890 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 P,X) call if the
368a0 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69 metadata is sti
368b0 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e ll valid or.** N
368c0 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 ULL if the metad
368d0 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 ata has been dis
368e0 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 carded..** ^Afte
368f0 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 r each call to s
36900 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
36910 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 ta(C,N,P,X) wher
36920 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c e X is not NULL,
36930 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 .** SQLite will
36940 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 invoke the destr
36950 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 uctor function X
36960 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 with parameter
36970 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 P exactly.** onc
36980 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 e, when the meta
36990 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65 data is discarde
369a0 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 d..** SQLite is
369b0 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 free to discard
369c0 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 the metadata at
369d0 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 any time, includ
369e0 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 ing: <ul>.** <li
369f0 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 > when the corre
36a00 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f sponding functio
36a10 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e n parameter chan
36a20 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 ges, or.** <li>
36a30 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 when [sqlite3_re
36a40 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
36a50 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 e3_finalize()] i
36a60 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 s called for the
36a70 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 .** SQL sta
36a80 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c tement, or.** <l
36a90 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f i> when sqlite3_
36aa0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 set_auxdata() is
36ab0 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f invoked again o
36ac0 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d n the same param
36ad0 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e eter, or.** <li>
36ae0 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 during the orig
36af0 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 inal sqlite3_set
36b00 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 _auxdata() call
36b10 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a when a memory .*
36b20 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f * allocatio
36b30 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 n error occurs.
36b40 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f </ul>)^.**.** No
36b50 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c te the last bull
36b60 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 et in particular
36b70 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f . The destructo
36b80 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 r X in .** sqlit
36b90 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 e3_set_auxdata(C
36ba0 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65 ,N,P,X) might be
36bb0 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 called immediat
36bc0 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a ely, before the.
36bd0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 ** sqlite3_set_a
36be0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
36bf0 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e ce even returns.
36c00 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f Hence sqlite3_
36c10 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a set_auxdata().**
36c20 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 should be calle
36c30 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f d near the end o
36c40 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 f the function i
36c50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e mplementation an
36c60 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f d the.** functio
36c70 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
36c80 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 should not make
36c90 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66 any use of P af
36ca0 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 ter.** sqlite3_s
36cb0 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73 et_auxdata() has
36cc0 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a been called..**
36cd0 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 .** ^(In practic
36ce0 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 e, metadata is p
36cf0 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e reserved between
36d00 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 function calls
36d10 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 for.** function
36d20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 parameters that
36d30 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 are compile-time
36d40 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c constants, incl
36d50 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a uding literal.**
36d60 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 values and [par
36d70 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70 ameters] and exp
36d80 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 ressions compose
36d90 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e d from the same.
36da0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 )^.**.** These r
36db0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
36dc0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
36dd0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
36de0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 hich.** the SQL
36df0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
36e00 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ing..*/.SQLITE_A
36e10 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f PI void *SQLITE_
36e20 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
36e30 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 get_auxdata(sqli
36e40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
36e50 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 t N);.SQLITE_API
36e60 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 void SQLITE_STD
36e70 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 65 74 CALL sqlite3_set
36e80 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 _auxdata(sqlite3
36e90 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e _context*, int N
36ea0 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a , void*, void (*
36eb0 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a )(void*));.../*.
36ec0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
36ed0 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 stants Defining
36ee0 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 Special Destruct
36ef0 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a or Behavior.**.*
36f00 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 * These are spec
36f10 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 ial values for t
36f20 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 he destructor th
36f30 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 at is passed in
36f40 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 as the.** final
36f50 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 argument to rout
36f60 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 ines like [sqlit
36f70 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 e3_result_blob()
36f80 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 ]. ^If the dest
36f90 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 ructor.** argume
36fa0 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 nt is SQLITE_STA
36fb0 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 TIC, it means th
36fc0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 at the content p
36fd0 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 ointer is consta
36fe0 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e nt.** and will n
36ff0 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 ever change. It
37000 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
37010 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 o be destroyed.
37020 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f ^The.** SQLITE_
37030 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 TRANSIENT value
37040 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 means that the c
37050 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 ontent will like
37060 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 ly change in.**
37070 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 the near future
37080 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 and that SQLite
37090 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 should make its
370a0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 own private copy
370b0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 of.** the conte
370c0 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e nt before return
370d0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ing..**.** The t
370e0 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 ypedef is necess
370f0 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 ary to work arou
37100 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 nd problems in c
37110 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f ertain.** C++ co
37120 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 mpilers..*/.type
37130 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 def void (*sqlit
37140 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 e3_destructor_ty
37150 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 pe)(void*);.#def
37160 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ine SQLITE_STATI
37170 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 C ((sqlite3
37180 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 _destructor_type
37190 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 )0).#define SQLI
371a0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 TE_TRANSIENT (
371b0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 (sqlite3_destruc
371c0 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a tor_type)-1)../*
371d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 .** CAPI3REF: Se
371e0 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 tting The Result
371f0 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 Of An SQL Funct
37200 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ion.** METHOD: s
37210 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a qlite3_context.*
37220 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
37230 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 nes are used by
37240 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 the xFunc or xFi
37250 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 nal callbacks th
37260 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 at.** implement
37270 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
37280 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 d aggregates. S
37290 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ee.** [sqlite3_c
372a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
372b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
372c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
372d0 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 ()].** for addit
372e0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
372f0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 n..**.** These f
37300 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 unctions work ve
37310 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 ry much like the
37320 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 [parameter bind
37330 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a ing] family of.*
37340 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 * functions used
37350 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 to bind values
37360 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 to host paramete
37370 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 rs in prepared s
37380 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 tatements..** Re
37390 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 fer to the [SQL
373a0 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d parameter] docum
373b0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 entation for add
373c0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
373d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ion..**.** ^The
373e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
373f0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 lob() interface
37400 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 sets the result
37410 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 from.** an appli
37420 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
37430 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 unction to be th
37440 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e e BLOB whose con
37450 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a tent is pointed.
37460 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 ** to by the sec
37470 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e ond parameter an
37480 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 d which is N byt
37490 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 es long where N
374a0 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 is the.** third
374b0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
374c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
374d0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c sult_zeroblob(C,
374e0 4e 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 N) and sqlite3_r
374f0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 esult_zeroblob64
37500 28 43 2c 4e 29 0a 2a 2a 20 69 6e 74 65 72 66 61 (C,N).** interfa
37510 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 ces set the resu
37520 6c 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 lt of the applic
37530 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
37540 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 nction to be.**
37550 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e a BLOB containin
37560 67 20 61 6c 6c 20 7a 65 72 6f 20 62 79 74 65 73 g all zero bytes
37570 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 and N bytes in
37580 73 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 size..**.** ^The
37590 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
375a0 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 double() interfa
375b0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 ce sets the resu
375c0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 lt from.** an ap
375d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
375e0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
375f0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e a floating poin
37600 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 t value specifie
37610 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 d.** by its 2nd
37620 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
37630 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
37640 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 ult_error() and
37650 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
37660 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f rror16() functio
37670 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 ns.** cause the
37680 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 implemented SQL
37690 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f function to thro
376a0 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a w an exception..
376b0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 ** ^SQLite uses
376c0 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 the string point
376d0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 ed to by the.**
376e0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
376f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37700 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 error() or sqlit
37710 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
37720 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 6().** as the te
37730 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d xt of an error m
37740 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 essage. ^SQLite
37750 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 interprets the
37760 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
37770 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c string from sql
37780 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
37790 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 r() as UTF-8. ^S
377a0 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 QLite.** interpr
377b0 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 ets the string f
377c0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 rom sqlite3_resu
377d0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 lt_error16() as
377e0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 UTF-16 in native
377f0 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 .** byte order.
37800 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 ^If the third p
37810 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
37820 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
37830 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
37840 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
37850 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 ) is negative th
37860 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 en SQLite takes
37870 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 as the error.**
37880 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 message all text
37890 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 up through the
378a0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 first zero chara
378b0 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 cter..** ^If the
378c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
378d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 to sqlite3_resu
378e0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a lt_error() or.**
378f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37900 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e error16() is non
37910 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 -negative then S
37920 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 QLite takes that
37930 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 many.** bytes (
37940 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 not characters)
37950 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 from the 2nd par
37960 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 ameter as the er
37970 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 ror message..**
37980 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
37990 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 ult_error() and
379a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
379b0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 rror16().** rout
379c0 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 ines make a priv
379d0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ate copy of the
379e0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 error message te
379f0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 xt before.** the
37a00 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 y return. Hence
37a10 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 , the calling fu
37a20 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c nction can deall
37a30 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 ocate or.** modi
37a40 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 fy the text afte
37a50 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 r they return wi
37a60 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e thout harm..** ^
37a70 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
37a80 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 lt_error_code()
37a90 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 function changes
37aa0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a the error code.
37ab0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 ** returned by S
37ac0 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c QLite as a resul
37ad0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e t of an error in
37ae0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 a function. ^B
37af0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 y default,.** th
37b00 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 e error code is
37b10 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e SQLITE_ERROR. ^
37b20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c A subsequent cal
37b30 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 l to sqlite3_res
37b40 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f ult_error().** o
37b50 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
37b60 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 _error16() reset
37b70 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 s the error code
37b80 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 to SQLITE_ERROR
37b90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
37ba0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
37bb0 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 r_toobig() inter
37bc0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 face causes SQLi
37bd0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a te to throw an.*
37be0 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 * error indicati
37bf0 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 ng that a string
37c00 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 or BLOB is too
37c10 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e long to represen
37c20 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 t..**.** ^The sq
37c30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
37c40 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 or_nomem() inter
37c50 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 face causes SQLi
37c60 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a te to throw an.*
37c70 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 * error indicati
37c80 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 ng that a memory
37c90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
37ca0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
37cb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
37cc0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 t() interface se
37cd0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ts the return va
37ce0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 lue.** of the ap
37cf0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
37d00 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
37d10 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e the 32-bit sign
37d20 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 ed integer.** va
37d30 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 lue given in the
37d40 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2nd argument..*
37d50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
37d60 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e esult_int64() in
37d70 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
37d80 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a return value.**
37d90 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
37da0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
37db0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 tion to be the 6
37dc0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 4-bit signed int
37dd0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 eger.** value gi
37de0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 ven in the 2nd a
37df0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e rgument..**.** ^
37e00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
37e10 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 lt_null() interf
37e20 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 ace sets the ret
37e30 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 urn value.** of
37e40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
37e50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
37e60 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a to be NULL..**.
37e70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
37e80 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 result_text(), s
37e90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
37ea0 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 xt16(),.** sqlit
37eb0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
37ec0 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 le(), and sqlite
37ed0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 3_result_text16b
37ee0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a e() interfaces.*
37ef0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e * set the return
37f00 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 value of the ap
37f10 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
37f20 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
37f30 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e .** a text strin
37f40 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 g which is repre
37f50 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c sented as UTF-8,
37f60 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 UTF-16 native b
37f70 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 yte order,.** UT
37f80 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 F-16 little endi
37f90 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 an, or UTF-16 bi
37fa0 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 g endian, respec
37fb0 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 tively..** ^The
37fc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
37fd0 65 78 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 ext64() interfac
37fe0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 e sets the retur
37ff0 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a n value of an.**
38000 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
38010 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
38020 20 62 65 20 61 20 74 65 78 74 20 73 74 72 69 6e be a text strin
38030 67 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 g in an encoding
38040 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 .** specified by
38050 20 74 68 65 20 66 69 66 74 68 20 28 61 6e 64 20 the fifth (and
38060 6c 61 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c last) parameter,
38070 20 77 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f which must be o
38080 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 ne.** of [SQLITE
38090 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f _UTF8], [SQLITE_
380a0 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f UTF16], [SQLITE_
380b0 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 UTF16BE], or [SQ
380c0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a LITE_UTF16LE]..*
380d0 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 * ^SQLite takes
380e0 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 the text result
380f0 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 from the applica
38100 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 tion from.** the
38110 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 2nd parameter o
38120 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 f the sqlite3_re
38130 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
38140 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 faces..** ^If th
38150 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
38160 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
38170 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
38180 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 rfaces.** is neg
38190 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 ative, then SQLi
381a0 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 te takes result
381b0 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e text from the 2n
381c0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 d parameter.** t
381d0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 hrough the first
381e0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e zero character.
381f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 .** ^If the 3rd
38200 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
38210 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
38220 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
38230 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 .** is non-negat
38240 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e ive, then as man
38250 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 y bytes (not cha
38260 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 racters) of the
38270 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 text.** pointed
38280 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 to by the 2nd pa
38290 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 rameter are take
382a0 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 n as the applica
382b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 tion-defined.**
382c0 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e function result.
382d0 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 If the 3rd par
382e0 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 ameter is non-ne
382f0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a gative, then it.
38300 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 ** must be the b
38310 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 yte offset into
38320 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 the string where
38330 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 the NUL termina
38340 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 tor would.** app
38350 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e ear if the strin
38360 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d g where NUL term
38370 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 inated. If any
38380 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f NUL characters o
38390 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 ccur.** in the s
383a0 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 tring at a byte
383b0 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c offset that is l
383c0 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c ess than the val
383d0 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a ue of the 3rd.**
383e0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e parameter, then
383f0 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 the resulting s
38400 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 tring will conta
38410 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 in embedded NULs
38420 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 and the.** resu
38430 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e lt of expression
38440 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 s operating on s
38450 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 trings with embe
38460 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 dded NULs is und
38470 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 efined..** ^If t
38480 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
38490 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
384a0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
384b0 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 erfaces.** or sq
384c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
384d0 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 b is a non-NULL
384e0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 pointer, then SQ
384f0 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a Lite calls that.
38500 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 ** function as t
38510 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e he destructor on
38520 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f the text or BLO
38530 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 B result when it
38540 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 has.** finished
38550 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 using that resu
38560 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 lt..** ^If the 4
38570 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
38580 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
38590 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
385a0 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c ces or to.** sql
385b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
385c0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 is the special
385d0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f constant SQLITE_
385e0 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c STATIC, then SQL
385f0 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 ite.** assumes t
38600 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 hat the text or
38610 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 BLOB result is i
38620 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 n constant space
38630 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a and does not.**
38640 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e copy the conten
38650 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 t of the paramet
38660 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 er nor call a de
38670 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 structor on the
38680 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 content.** when
38690 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 it has finished
386a0 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c using that resul
386b0 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 t..** ^If the 4t
386c0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
386d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
386e0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
386f0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 es.** or sqlite3
38700 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 _result_blob is
38710 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 the special cons
38720 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e tant SQLITE_TRAN
38730 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 SIENT.** then SQ
38740 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 Lite makes a cop
38750 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 y of the result
38760 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 into space obtai
38770 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d ned from.** from
38780 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
38790 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 ()] before it