0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 rograms. If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 s file, then it
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 ite, is subject
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 erimental". Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 to SQLite. We
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 e changes.** to
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69 ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67 n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73 est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20 C-language API
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69 r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73 e. This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69 the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 ve source.** on
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72 how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73 faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 ion number) and
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 to "sqlite3.h"
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 ITE3_H_.#define
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 lude <stdarg.h>
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 /*.** Make sure
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61 ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69 bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75 de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 TE_API.# define
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20 _CDECL.# define
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66 TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20 ros are used in
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 e.** interfaces
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63 as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65 ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 ntal. New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63 d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20 ated interfaces
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 ity only. Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 ese macros used
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 sages when they
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 were used. But
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 magic ended up
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 generating such
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 a flurry of bug
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 reports.** that
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 e back to using
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 not defined by
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 n Numbers.**.**
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20 Lite3) and Y is
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72 _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 0 + Y*1000 + Z)
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 where X, Y, and
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69 * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 te will also.**
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 he release from
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69 which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77 ved. Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 system</a>. ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f m. ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31 UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20 .** hash of the
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72 entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 QLITE_VERSION
10a0: 20 20 20 20 20 22 33 2e 38 2e 31 32 22 0a 23 64 "3.8.12".#d
10b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 efine SQLITE_VER
10c0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 38 SION_NUMBER 3008
10d0: 30 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 012.#define SQLI
10e0: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20 TE_SOURCE_ID
10f0: 20 20 22 32 30 31 35 2d 31 30 2d 30 36 20 30 31 "2015-10-06 01
1100: 3a 34 34 3a 35 33 20 33 31 36 38 33 32 36 65 62 :44:53 3168326eb
1110: 66 61 31 63 39 36 31 64 38 66 63 36 34 33 35 34 fa1c961d8fc64354
1120: 35 33 62 30 32 62 65 32 33 64 39 31 30 63 63 22 53b02be23d910cc"
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 6f 66 20 73 71 6c 69 74 r of.** of sqlit
3ac0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 e3_exec() after
3ad0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
3ae0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c e string is no l
3af0: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a onger needed..**
3b00: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 ^If the 5th par
3b10: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3b20: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 3_exec() is not
3b30: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f NULL and no erro
3b40: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 rs.** occur, the
3b50: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 n sqlite3_exec()
3b60: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 sets the pointe
3b70: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 r in its 5th par
3b80: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c ameter to.** NUL
3b90: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 L before returni
3ba0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e ng..**.** ^If an
3bb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3bc0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
3bd0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 non-zero, the s
3be0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
3bf0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
3c00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 SQLITE_ABORT wi
3c10: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 thout invoking t
3c20: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 he callback agai
3c30: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 n and.** without
3c40: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 running any sub
3c50: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 sequent SQL stat
3c60: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ements..**.** ^T
3c70: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 he 2nd argument
3c80: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 to the sqlite3_e
3c90: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 xec() callback f
3ca0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a unction is the.*
3cb0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 * number of colu
3cc0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
3cd0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 t. ^The 3rd arg
3ce0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c ument to the sql
3cf0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 ite3_exec().** c
3d00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 allback is an ar
3d10: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
3d20: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 to strings obtai
3d30: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a ned as if from.*
3d40: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
3d50: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 n_text()], one f
3d60: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 or each column.
3d70: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 ^If an element
3d80: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 of a.** result r
3d90: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 ow is NULL then
3da0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
3db0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 g string pointer
3dc0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 for the.** sqli
3dd0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 te3_exec() callb
3de0: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ack is a NULL po
3df0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 inter. ^The 4th
3e00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
3e10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3e20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 () callback is a
3e30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
3e40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 ers to strings w
3e50: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 here each.** ent
3e60: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 ry represents th
3e70: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 e name of corres
3e80: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 ponding result c
3e90: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 olumn as obtaine
3ea0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
3eb0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
3ec0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 ]..**.** ^If the
3ed0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 2nd parameter t
3ee0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
3ef0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
3f00: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a er, a pointer.**
3f10: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 to an empty str
3f20: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 ing, or a pointe
3f30: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 r that contains
3f40: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 only whitespace
3f50: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 and/or .** SQL c
3f60: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f omments, then no
3f70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
3f80: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e are evaluated an
3f90: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a d the database.*
3fa0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 * is not changed
3fb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 ..**.** Restrict
3fc0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ions:.**.** <ul>
3fd0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 .** <li> The app
3fe0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e lication must en
3ff0: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 sure that the 1s
4000: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
4010: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
4020: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 is a valid
4030: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 and open [datab
4040: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
4050: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 .** <li> The app
4060: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f lication must no
4070: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 t close the [dat
4080: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
4090: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a ] specified by.*
40a0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 * the 1st p
40b0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
40c0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 te3_exec() while
40d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
40e0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c is running..** <
40f0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 li> The applicat
4100: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 ion must not mod
4110: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 ify the SQL stat
4120: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 ement text passe
4130: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 d into.** t
4140: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
4150: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 of sqlite3_exec
4160: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 () while sqlite3
4170: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 _exec() is runni
4180: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a ng..** </ul>.*/.
4190: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
41a0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
41b0: 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 lite3_exec(. sq
41c0: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 lite3*,
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41e0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f /* An o
41f0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a pen database */.
4200: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 const char *sq
4210: 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 l,
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
4230: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 SQL to be evalua
4240: 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 ted */. int (*c
4250: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 allback)(void*,i
4260: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a nt,char**,char**
4270: 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 ), /* Callback
4280: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f function */. vo
4290: 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 id *,
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
42b0: 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 /* 1st
42c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c argument to call
42d0: 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a back */. char *
42e0: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 *errmsg
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4300: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 /* Error ms
4310: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a g written here *
4320: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
4330: 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 3REF: Result Cod
4340: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
4350: 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 {result code def
4360: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 initions}.**.**
4370: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 Many SQLite func
4380: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 tions return an
4390: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 integer result c
43a0: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 ode from the set
43b0: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 shown.** here i
43c0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 n order to indic
43d0: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 ate success or f
43e0: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 ailure..**.** Ne
43f0: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 w error codes ma
4400: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
4410: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
4420: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 SQLite..**.** S
4430: 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 ee also: [extend
4440: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 ed result code d
4450: 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 efinitions].*/.#
4460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b define SQLITE_OK
4470: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 0 /
4480: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 * Successful res
4490: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e ult */./* beginn
44a0: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 ing-of-error-cod
44b0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 es */.#define SQ
44c0: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 LITE_ERROR
44d0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 1 /* SQL err
44e0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 or or missing da
44f0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e tabase */.#defin
4500: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 e SQLITE_INTERNA
4510: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 L 2 /* Int
4520: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f ernal logic erro
4530: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 r in SQLite */.#
4540: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 define SQLITE_PE
4550: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f RM 3 /
4560: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 * Access permiss
4570: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 ion denied */.#d
4580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f efine SQLITE_ABO
4590: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a RT 4 /*
45a0: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e Callback routin
45b0: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 e requested an a
45c0: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 bort */.#define
45d0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 SQLITE_BUSY
45e0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 5 /* The d
45f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 atabase file is
4600: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e locked */.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 e SQLITE_LOCKED
4620: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 6 /* A t
4630: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 able in the data
4640: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a base is locked *
4650: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4660: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 _NOMEM 7
4670: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 /* A malloc()
4680: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e failed */.#defin
4690: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
46a0: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 Y 8 /* Att
46b0: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 empt to write a
46c0: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 readonly databas
46d0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
46e0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 ITE_INTERRUPT
46f0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 9 /* Operatio
4700: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 n terminated by
4710: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
4720: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t()*/.#define SQ
4730: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 LITE_IOERR
4740: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 10 /* Some ki
4750: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 nd of disk I/O e
4760: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f rror occurred */
4770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4780: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 CORRUPT 11
4790: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
47a0: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d disk image is m
47b0: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 alformed */.#def
47c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f ine SQLITE_NOTFO
47d0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 UND 12 /* U
47e0: 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e nknown opcode in
47f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f sqlite3_file_co
4800: 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 ntrol() */.#defi
4810: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 ne SQLITE_FULL
4820: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 13 /* In
4830: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 sertion failed b
4840: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 ecause database
4850: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 is full */.#defi
4860: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 ne SQLITE_CANTOP
4870: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e EN 14 /* Un
4880: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 able to open the
4890: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a database file *
48a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
48b0: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 _PROTOCOL 15
48c0: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f /* Database lo
48d0: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f ck protocol erro
48e0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
48f0: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 ITE_EMPTY
4900: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 16 /* Database
4910: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 is empty */.#de
4920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 fine SQLITE_SCHE
4930: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 MA 17 /*
4940: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 The database sch
4950: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 ema changed */.#
4960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f define SQLITE_TO
4970: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f OBIG 18 /
4980: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 * String or BLOB
4990: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 exceeds size li
49a0: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 mit */.#define S
49b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
49c0: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 19 /* Abort
49d0: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e due to constrain
49e0: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 t violation */.#
49f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 define SQLITE_MI
4a00: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f SMATCH 20 /
4a10: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d * Data type mism
4a20: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 atch */.#define
4a30: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 SQLITE_MISUSE
4a40: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 21 /* Libra
4a50: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 ry used incorrec
4a60: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 tly */.#define S
4a70: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 QLITE_NOLFS
4a80: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 22 /* Uses O
4a90: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 S features not s
4aa0: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 upported on host
4ab0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4ac0: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 TE_AUTH 2
4ad0: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 3 /* Authoriza
4ae0: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 tion denied */.#
4af0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f define SQLITE_FO
4b00: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f RMAT 24 /
4b10: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 * Auxiliary data
4b20: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f base format erro
4b30: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
4b40: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 ITE_RANGE
4b50: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 25 /* 2nd para
4b60: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
4b70: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e _bind out of ran
4b80: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ge */.#define SQ
4b90: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 LITE_NOTADB
4ba0: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 26 /* File op
4bb0: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 ened that is not
4bc0: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
4bd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4be0: 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32 TE_NOTICE 2
4bf0: 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 7 /* Notificat
4c00: 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 ions from sqlite
4c10: 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 3_log() */.#defi
4c20: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e ne SQLITE_WARNIN
4c30: 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61 G 28 /* Wa
4c40: 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 rnings from sqli
4c50: 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 te3_log() */.#de
4c60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 fine SQLITE_ROW
4c70: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 100 /*
4c80: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 sqlite3_step() h
4c90: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 as another row r
4ca0: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 eady */.#define
4cb0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 SQLITE_DONE
4cc0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 101 /* sqlit
4cd0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 e3_step() has fi
4ce0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 nished executing
4cf0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 */./* end-of-er
4d00: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a ror-codes */../*
4d10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 .** CAPI3REF: Ex
4d20: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f tended Result Co
4d30: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a des.** KEYWORDS:
4d40: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c {extended resul
4d50: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f t code definitio
4d60: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 ns}.**.** In its
4d70: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
4d80: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 ration, SQLite A
4d90: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 PI routines retu
4da0: 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74 rn one of 30 int
4db0: 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 eger.** [result
4dc0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 codes]. However
4dd0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 , experience has
4de0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 shown that many
4df0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 of.** these res
4e00: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f ult codes are to
4e10: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 o coarse-grained
4e20: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 . They do not p
4e30: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 rovide as.** muc
4e40: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 h information ab
4e50: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 out problems as
4e60: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 programmers migh
4e70: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 t like. In an e
4e80: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 ffort to.** addr
4e90: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 ess this, newer
4ea0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
4eb0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e te (version 3.3.
4ec0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 8 and later) inc
4ed0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 lude.** support
4ee0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 for additional r
4ef0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 esult codes that
4f00: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 provide more de
4f10: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 tailed informati
4f20: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f on.** about erro
4f30: 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74 65 6e rs. These [exten
4f40: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
4f50: 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 ] are enabled or
4f60: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 disabled.** on
4f70: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63 a per database c
4f80: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 onnection basis
4f90: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 using the.** [sq
4fa0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 lite3_extended_r
4fb0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 esult_codes()] A
4fc0: 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 74 PI. Or, the ext
4fd0: 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a ended code for.*
4fe0: 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e * the most recen
4ff0: 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65 20 6f t error can be o
5000: 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a btained using.**
5010: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 [sqlite3_extend
5020: 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a ed_errcode()]..*
5030: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5040: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 _IOERR_READ
5050: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5060: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 _IOERR | (1<<8))
5070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5080: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 IOERR_SHORT_READ
5090: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
50a0: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a IOERR | (2<<8)).
50b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
50c0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 OERR_WRITE
50d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
50e0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 OERR | (3<<8)).#
50f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5100: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 ERR_FSYNC
5110: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5120: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 ERR | (4<<8)).#d
5130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5140: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 RR_DIR_FSYNC
5150: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5160: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 RR | (5<<8)).#de
5170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
5180: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 R_TRUNCATE
5190: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
51a0: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 R | (6<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
51c0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 _FSTAT
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
51e0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 | (7<<8)).#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5200: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 UNLOCK
5210: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5220: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (8<<8)).#defin
5230: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 e SQLITE_IOERR_R
5240: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 DLOCK
5250: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5260: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (9<<8)).#define
5270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 SQLITE_IOERR_DE
5280: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
5290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
52a0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (10<<8)).#define
52b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c SQLITE_IOERR_BL
52c0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 OCKED
52d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
52e0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (11<<8)).#define
52f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f SQLITE_IOERR_NO
5300: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 MEM
5310: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5320: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (12<<8)).#define
5330: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 SQLITE_IOERR_AC
5340: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 CESS
5350: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5360: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (13<<8)).#define
5370: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 SQLITE_IOERR_CH
5380: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 ECKRESERVEDLOCK
5390: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
53a0: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (14<<8)).#define
53b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f SQLITE_IOERR_LO
53c0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CK
53d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
53e0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (15<<8)).#define
53f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c SQLITE_IOERR_CL
5400: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 OSE
5410: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5420: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (16<<8)).#define
5430: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 SQLITE_IOERR_DI
5440: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 R_CLOSE
5450: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5460: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (17<<8)).#define
5470: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
5480: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 MOPEN
5490: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
54a0: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (18<<8)).#define
54b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
54c0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 MSIZE
54d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
54e0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (19<<8)).#define
54f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
5500: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 MLOCK
5510: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5520: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (20<<8)).#define
5530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
5540: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 MMAP
5550: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5560: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (21<<8)).#define
5570: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 SQLITE_IOERR_SE
5580: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 EK
5590: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
55a0: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (22<<8)).#define
55b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 SQLITE_IOERR_DE
55c0: 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 LETE_NOENT
55d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
55e0: 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (23<<8)).#define
55f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d SQLITE_IOERR_MM
5600: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AP
5610: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5620: 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (24<<8)).#define
5630: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 SQLITE_IOERR_GE
5640: 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 TTEMPPATH
5650: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5660: 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (25<<8)).#define
5670: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f SQLITE_IOERR_CO
5680: 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20 NVPATH
5690: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
56a0: 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (26<<8)).#define
56b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e SQLITE_IOERR_VN
56c0: 4f 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ODE
56d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
56e0: 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (27<<8)).#define
56f0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 SQLITE_LOCKED_S
5700: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 HAREDCACHE
5710: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c (SQLITE_LOCKED |
5720: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (1<<8)).#defin
5730: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 e SQLITE_BUSY_RE
5740: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 COVERY
5750: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 (SQLITE_BUSY
5760: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
5770: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 ne SQLITE_BUSY_S
5780: 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 NAPSHOT
5790: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 (SQLITE_BUSY
57a0: 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 | (2<<8)).#def
57b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
57c0: 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 PEN_NOTEMPDIR
57d0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f (SQLITE_CANTO
57e0: 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 PEN | (1<<8)).#d
57f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
5800: 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 TOPEN_ISDIR
5810: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e (SQLITE_CAN
5820: 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a TOPEN | (2<<8)).
5830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5840: 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 ANTOPEN_FULLPATH
5850: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
5860: 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 ANTOPEN | (3<<8)
5870: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5880: 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 _CANTOPEN_CONVPA
5890: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 TH (SQLITE
58a0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c _CANTOPEN | (4<<
58b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
58c0: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 TE_CORRUPT_VTAB
58d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
58e0: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c TE_CORRUPT | (1<
58f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5900: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 ITE_READONLY_REC
5910: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c OVERY (SQL
5920: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 ITE_READONLY | (
5930: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5940: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 QLITE_READONLY_C
5950: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 ANTLOCK (S
5960: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c QLITE_READONLY |
5970: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
5980: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 SQLITE_READONLY
5990: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 _ROLLBACK
59a0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 (SQLITE_READONLY
59b0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 | (3<<8)).#defi
59c0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e ne SQLITE_READON
59d0: 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20 LY_DBMOVED
59e0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e (SQLITE_READON
59f0: 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 LY | (4<<8)).#de
5a00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 fine SQLITE_ABOR
5a10: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 T_ROLLBACK
5a20: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 (SQLITE_ABOR
5a30: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 T | (2<<8)).#def
5a40: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5a50: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 RAINT_CHECK
5a60: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5a70: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a RAINT | (1<<8)).
5a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5a90: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 ONSTRAINT_COMMIT
5aa0: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 HOOK (SQLITE_C
5ab0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c ONSTRAINT | (2<<
5ac0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5ad0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f TE_CONSTRAINT_FO
5ae0: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 REIGNKEY (SQLI
5af0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5b00: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (3<<8)).#define
5b10: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5b20: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 T_FUNCTION (
5b30: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5b40: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 T | (4<<8)).#def
5b50: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5b60: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 RAINT_NOTNULL
5b70: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5b80: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a RAINT | (5<<8)).
5b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5ba0: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 ONSTRAINT_PRIMAR
5bb0: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 YKEY (SQLITE_C
5bc0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c ONSTRAINT | (6<<
5bd0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5be0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 TE_CONSTRAINT_TR
5bf0: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 IGGER (SQLI
5c00: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5c10: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (7<<8)).#define
5c20: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5c30: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 T_UNIQUE (
5c40: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5c50: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 T | (8<<8)).#def
5c60: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5c70: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 RAINT_VTAB
5c80: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5c90: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a RAINT | (9<<8)).
5ca0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5cb0: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 ONSTRAINT_ROWID
5cc0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
5cd0: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c ONSTRAINT |(10<<
5ce0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5cf0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 TE_NOTICE_RECOVE
5d00: 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49 R_WAL (SQLI
5d10: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c TE_NOTICE | (1<<
5d20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5d30: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 TE_NOTICE_RECOVE
5d40: 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 R_ROLLBACK (SQLI
5d50: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c TE_NOTICE | (2<<
5d60: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5d70: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 TE_WARNING_AUTOI
5d80: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49 NDEX (SQLI
5d90: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c TE_WARNING | (1<
5da0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5db0: 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20 20 ITE_AUTH_USER
5dc0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5dd0: 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 ITE_AUTH | (1<<8
5de0: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ))../*.** CAPI3R
5df0: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 EF: Flags For Fi
5e00: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f le Open Operatio
5e10: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 ns.**.** These b
5e20: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e it values are in
5e30: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
5e40: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 n the.** 3rd par
5e50: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ameter to the [s
5e60: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
5e70: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a ] interface and.
5e80: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 ** in the 4th pa
5e90: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b rameter to the [
5ea0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 sqlite3_vfs.xOpe
5eb0: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 n] method..*/.#d
5ec0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5ed0: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 N_READONLY
5ee0: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 0x00000001 /
5ef0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
5f00: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
5f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5f20: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 N_READWRITE
5f30: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 0x00000002 /
5f40: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
5f50: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
5f60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5f70: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 N_CREATE
5f80: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 0x00000004 /
5f90: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
5fa0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
5fb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5fc0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 N_DELETEONCLOSE
5fd0: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 0x00000008 /
5fe0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
5ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6000: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 N_EXCLUSIVE
6010: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 0x00000010 /
6020: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6040: 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 N_AUTOPROXY
6050: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 0x00000020 /
6060: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6080: 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 N_URI
6090: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 0x00000040 /
60a0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
60b0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
60c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
60d0: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 N_MEMORY
60e0: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 0x00000080 /
60f0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
6100: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
6110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6120: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 N_MAIN_DB
6130: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 0x00000100 /
6140: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6150: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6160: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 N_TEMP_DB
6170: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 0x00000200 /
6180: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
61a0: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 N_TRANSIENT_DB
61b0: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 0x00000400 /
61c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
61e0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 N_MAIN_JOURNAL
61f0: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 0x00000800 /
6200: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6220: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 N_TEMP_JOURNAL
6230: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 0x00001000 /
6240: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6260: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 N_SUBJOURNAL
6270: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 0x00002000 /
6280: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6290: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
62a0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c N_MASTER_JOURNAL
62b0: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 0x00004000 /
62c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
62d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
62e0: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 N_NOMUTEX
62f0: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 0x00008000 /
6300: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
6310: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
6320: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6330: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 N_FULLMUTEX
6340: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 0x00010000 /
6350: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
6360: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
6370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6380: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 N_SHAREDCACHE
6390: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 0x00020000 /
63a0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
63b0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
63c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
63d0: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 N_PRIVATECACHE
63e0: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 0x00040000 /
63f0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
6400: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
6410: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6420: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 N_WAL
6430: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 0x00080000 /
6440: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f * VFS only */../
6450: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 * Reserved:
6460: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6470: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 0x00F00000 *
6480: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
6490: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 F: Device Charac
64a0: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 teristics.**.**
64b0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 The xDeviceChara
64c0: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f cteristics metho
64d0: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 d of the [sqlite
64e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 3_io_methods].**
64f0: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 object returns
6500: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 an integer which
6510: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 is a vector of
6520: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c these.** bit val
6530: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 ues expressing I
6540: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 /O characteristi
6550: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 cs of the mass s
6560: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 torage.** device
6570: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 that holds the
6580: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 file that the [s
6590: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
65a0: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e s].** refers to.
65b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
65c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
65d0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
65e0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
65f0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
6600: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
6610: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6620: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
6630: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
6640: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
6650: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
6660: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
6670: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
6680: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
6690: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
66a0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
66b0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
66c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
66d0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
66e0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
66f0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
6700: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
6710: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
6720: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
6730: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
6740: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
6750: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
6760: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
6770: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6780: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
6790: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
67a0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
67b0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
67c0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
67d0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
67e0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 to xWrite(). T
67f0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
6800: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
6810: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 ITE property mea
6820: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 ns that.** after
6830: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e reboot followin
6840: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 g a crash or pow
6850: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c er loss, the onl
6860: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 y bytes in a.**
6870: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 file that were w
6880: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 ritten at the ap
6890: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 plication level
68a0: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 might have chang
68b0: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 ed.** and that a
68c0: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 djacent bytes, e
68d0: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e ven bytes within
68e0: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 the same sector
68f0: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 are.** guarante
6900: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 ed to be unchang
6910: 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f ed. The SQLITE_
6920: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c IOCAP_UNDELETABL
6930: 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 E_WHEN_OPEN.** f
6940: 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61 lag indicate tha
6950: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 t a file cannot
6960: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 be deleted when
6970: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 open. The.** SQ
6980: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 LITE_IOCAP_IMMUT
6990: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 ABLE flag indica
69a0: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c tes that the fil
69b0: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d e is on.** read-
69c0: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 only media and c
69d0: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 annot be changed
69e0: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 even by process
69f0: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 es with.** eleva
6a00: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a ted privileges..
6a10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6a20: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 E_IOCAP_ATOMIC
6a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
6a40: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e x00000001.#defin
6a50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6a60: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 TOMIC512
6a70: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
6a80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6a90: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 IOCAP_ATOMIC1K
6aa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6ab0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 0000004.#define
6ac0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6ad0: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 MIC2K
6ae0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 0x00000008.#
6af0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6b00: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 CAP_ATOMIC4K
6b10: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6b20: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 00010.#define SQ
6b30: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6b40: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C8K
6b50: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 0x00000020.#de
6b60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6b70: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 P_ATOMIC16K
6b80: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6b90: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 040.#define SQLI
6ba0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 TE_IOCAP_ATOMIC3
6bb0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2K
6bc0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 0x00000080.#defi
6bd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6be0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 ATOMIC64K
6bf0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 0x0000010
6c00: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
6c10: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
6c20: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 ND 0x
6c30: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 00000200.#define
6c40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
6c50: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 QUENTIAL
6c60: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0x00000400.
6c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6c80: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 OCAP_UNDELETABLE
6c90: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 _WHEN_OPEN 0x00
6ca0: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 000800.#define S
6cb0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
6cc0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 RSAFE_OVERWRITE
6cd0: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 0x00001000.#d
6ce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
6cf0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 AP_IMMUTABLE
6d00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
6d10: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 2000../*.** CAPI
6d20: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 3REF: File Locki
6d30: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 ng Levels.**.**
6d40: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 SQLite uses one
6d50: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 of these integer
6d60: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
6d70: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e econd.** argumen
6d80: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 t to calls it ma
6d90: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b kes to the xLock
6da0: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 () and xUnlock()
6db0: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 methods.** of a
6dc0: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 n [sqlite3_io_me
6dd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a thods] object..*
6de0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6df0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 _LOCK_NONE
6e00: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
6e10: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
6e20: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
6e30: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 e SQLITE_LOCK_RE
6e40: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 SERVED 2.#d
6e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
6e60: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 K_PENDING
6e70: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
6e80: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 _LOCK_EXCLUSIVE
6e90: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 4../*.** CAP
6ea0: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 I3REF: Synchroni
6eb0: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 zation Type Flag
6ec0: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c s.**.** When SQL
6ed0: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 ite invokes the
6ee0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f xSync() method o
6ef0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 f an.** [sqlite3
6f00: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
6f10: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f ect it uses a co
6f20: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 mbination of.**
6f30: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 these integer va
6f40: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f lues as the seco
6f50: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
6f60: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 ** When the SQLI
6f70: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
6f80: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 flag is used, i
6f90: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 t means that the
6fa0: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 .** sync operati
6fb0: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f on only needs to
6fc0: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d flush data to m
6fd0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e ass storage. In
6fe0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 ode.** informati
6ff0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 on need not be f
7000: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c lushed. If the l
7010: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f ower four bits o
7020: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 f the flag.** eq
7030: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ual SQLITE_SYNC_
7040: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 NORMAL, that mea
7050: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c ns to use normal
7060: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 fsync() semanti
7070: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f cs..** If the lo
7080: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 wer four bits eq
7090: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ual SQLITE_SYNC_
70a0: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 FULL, that means
70b0: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f .** to use Mac O
70c0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 S X style fullsy
70d0: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 nc instead of fs
70e0: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 ync()..**.** Do
70f0: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 not confuse the
7100: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
7110: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 AL and SQLITE_SY
7120: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a NC_FULL flags.**
7130: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d with the [PRAGM
7140: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e A synchronous]=N
7150: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d ORMAL and [PRAGM
7160: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 A synchronous]=F
7170: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e ULL.** settings.
7180: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f The [synchrono
7190: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 us pragma] deter
71a0: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 mines when calls
71b0: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 to the.** xSync
71c0: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 VFS method occu
71d0: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e r and applies un
71e0: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 iformly across a
71f0: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a ll platforms..**
7200: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 The SQLITE_SYNC
7210: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 _NORMAL and SQLI
7220: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 TE_SYNC_FULL fla
7230: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 gs determine how
7240: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 .** energetic or
7250: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 rigorous or for
7260: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f ceful the sync o
7270: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e perations are an
7280: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 d.** only make a
7290: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d difference on M
72a0: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 ac OSX for the d
72b0: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f efault SQLite co
72c0: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 de..** (Third-pa
72d0: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e rty VFS implemen
72e0: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c tations might al
72f0: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 so make the dist
7300: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 inction.** betwe
7310: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e en SQLITE_SYNC_N
7320: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 ORMAL and SQLITE
7330: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 _SYNC_FULL, but
7340: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 among the.** ope
7350: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e rating systems n
7360: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 atively supporte
7370: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c d by SQLite, onl
7380: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 y Mac OSX.** car
7390: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 es about the dif
73a0: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 ference.).*/.#de
73b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 fine SQLITE_SYNC
73c0: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 _NORMAL 0
73d0: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 x00002.#define S
73e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 QLITE_SYNC_FULL
73f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0x00003
7400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7410: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 SYNC_DATAONLY
7420: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 0x00010../*.*
7430: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
7440: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 nterface Open Fi
7450: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 le Handle.**.**
7460: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 An [sqlite3_file
7470: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 ] object represe
7480: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 nts an open file
7490: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c in the .** [sql
74a0: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e ite3_vfs | OS in
74b0: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 terface layer].
74c0: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 Individual OS i
74d0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c nterface.** impl
74e0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c ementations will
74f0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 .** want to subc
7500: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 lass this object
7510: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 by appending ad
7520: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a ditional fields.
7530: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e ** for their own
7540: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 use. The pMeth
7550: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 ods entry is a p
7560: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
7570: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
7580: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 ods] object that
7590: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 defines methods
75a0: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a for performing.
75b0: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e ** I/O operation
75c0: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 s on the open fi
75d0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 le..*/.typedef s
75e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 truct sqlite3_fi
75f0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b le sqlite3_file;
7600: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
7610: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 file {. const s
7620: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
7630: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f _methods *pMetho
7640: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 ds; /* Methods
7650: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 for an open file
7660: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
7670: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
7680: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 face File Virtua
7690: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 l Methods Object
76a0: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c .**.** Every fil
76b0: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 e opened by the
76c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
76d0: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c en] method popul
76e0: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 ates an.** [sqli
76f0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
7700: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f (or, more commo
7710: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 nly, a subclass
7720: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
7730: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 e3_file] object)
7740: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
7750: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
7760: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a f this object..*
7770: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 * This object de
7780: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 fines the method
7790: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 s used to perfor
77a0: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 m various operat
77b0: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 ions.** against
77c0: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 the open file re
77d0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 presented by the
77e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
77f0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 object..**.** If
7800: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
7810: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 s.xOpen] method
7820: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 sets the sqlite3
7830: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 _file.pMethods e
7840: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 lement .** to a
7850: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
7860: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 , then the sqlit
7870: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 e3_io_methods.xC
7880: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d lose method.** m
7890: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 ay be invoked ev
78a0: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 en if the [sqlit
78b0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 e3_vfs.xOpen] re
78c0: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 ported that it f
78d0: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f ailed. The.** o
78e0: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 nly way to preve
78f0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c nt a call to xCl
7900: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 ose following a
7910: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f failed [sqlite3_
7920: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 vfs.xOpen].** is
7930: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 for the [sqlite
7940: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 3_vfs.xOpen] to
7950: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f set the sqlite3_
7960: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c file.pMethods el
7970: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c ement.** to NULL
7980: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
7990: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 s argument to xS
79a0: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f ync may be one o
79b0: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e f [SQLITE_SYNC_N
79c0: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 ORMAL] or.** [SQ
79d0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e LITE_SYNC_FULL].
79e0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 The first choi
79f0: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c ce is the normal
7a00: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 fsync()..** The
7a10: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 second choice i
7a20: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 s a Mac OS X sty
7a30: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 le fullsync. Th
7a40: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 e [SQLITE_SYNC_D
7a50: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 ATAONLY].** flag
7a60: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 may be ORed in
7a70: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 to indicate that
7a80: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f only the data o
7a90: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e f the file.** an
7aa0: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 d not its inode
7ab0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 needs to be sync
7ac0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e ed..**.** The in
7ad0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 teger values to
7ae0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c xLock() and xUnl
7af0: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 ock() are one of
7b00: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
7b10: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
7b20: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 NE],.** <li> [SQ
7b30: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
7b40: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
7b50: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 TE_LOCK_RESERVED
7b60: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
7b70: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d TE_LOCK_PENDING]
7b80: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 , or.** <li> [SQ
7b90: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
7ba0: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a IVE]..** </ul>.*
7bb0: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 * xLock() increa
7bc0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 ses the lock. xU
7bd0: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 nlock() decrease
7be0: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 s the lock..** T
7bf0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 he xCheckReserve
7c00: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 dLock() method c
7c10: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e hecks whether an
7c20: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 y database conne
7c30: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 ction,.** either
7c40: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 in this process
7c50: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 or in some othe
7c60: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f r process, is ho
7c70: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 lding a RESERVED
7c80: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 ,.** PENDING, or
7c90: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 EXCLUSIVE lock
7ca0: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 on the file. It
7cb0: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a returns true.**
7cc0: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 if such a lock
7cd0: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 exists and false
7ce0: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a otherwise..**.*
7cf0: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 * The xFileContr
7d00: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 ol() method is a
7d10: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 generic interfa
7d20: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 ce that allows c
7d30: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 ustom.** VFS imp
7d40: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 lementations to
7d50: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c directly control
7d60: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 an open file us
7d70: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
7d80: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
7d90: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ()] interface.
7da0: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 The second "op"
7db0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a argument is an.*
7dc0: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 * integer opcode
7dd0: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 . The third arg
7de0: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 ument is a gener
7df0: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e ic pointer inten
7e00: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 ded to.** point
7e10: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 to a structure t
7e20: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 hat may contain
7e30: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 arguments or spa
7e40: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a ce in which to.*
7e50: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 * write return v
7e60: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 alues. Potentia
7e70: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 l uses for xFile
7e80: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 Control() might
7e90: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 be.** functions
7ea0: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 to enable blocki
7eb0: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 ng locks with ti
7ec0: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 meouts, to chang
7ed0: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 e the.** locking
7ee0: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 strategy (for e
7ef0: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f xample to use do
7f00: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 t-file locks), t
7f10: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f o inquire.** abo
7f20: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 ut the status of
7f30: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 a lock, or to b
7f40: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 reak stale locks
7f50: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a . The SQLite.**
7f60: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 core reserves a
7f70: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 ll opcodes less
7f80: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 than 100 for its
7f90: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b own use..** A [
7fa0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 file control opc
7fb0: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f odes | list of o
7fc0: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 pcodes] less tha
7fd0: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 n 100 is availab
7fe0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 le..** Applicati
7ff0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 ons that define
8000: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f a custom xFileCo
8010: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f ntrol method sho
8020: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a uld use opcodes.
8030: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 ** greater than
8040: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 100 to avoid con
8050: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 flicts. VFS imp
8060: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
8070: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 uld.** return [S
8080: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 QLITE_NOTFOUND]
8090: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c for file control
80a0: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 opcodes that th
80b0: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 ey do not.** rec
80c0: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 ognize..**.** Th
80d0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 e xSectorSize()
80e0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 method returns t
80f0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f he sector size o
8100: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 f the.** device
8110: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 that underlies t
8120: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 he file. The se
8130: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 ctor size is the
8140: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 .** minimum writ
8150: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 e that can be pe
8160: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 rformed without
8170: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 disturbing.** ot
8180: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 her bytes in the
8190: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 file. The xDev
81a0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
81b0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 cs().** method r
81c0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 eturns a bit vec
81d0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 tor describing b
81e0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a ehaviors of the.
81f0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 ** underlying de
8200: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e vice:.**.** <ul>
8210: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8220: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a _IOCAP_ATOMIC].*
8230: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
8240: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a OCAP_ATOMIC512].
8250: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8260: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a IOCAP_ATOMIC1K].
8270: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8280: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a IOCAP_ATOMIC2K].
8290: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
82a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a IOCAP_ATOMIC4K].
82b0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
82c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a IOCAP_ATOMIC8K].
82d0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
82e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d IOCAP_ATOMIC16K]
82f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8300: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b _IOCAP_ATOMIC32K
8310: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
8320: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 E_IOCAP_ATOMIC64
8330: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
8340: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
8350: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 PEND].** <li> [S
8360: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
8370: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e ENTIAL].** </ul>
8380: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
8390: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
83a0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
83b0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
83c0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
83d0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
83e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
83f0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
8400: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
8410: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
8420: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
8430: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
8440: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
8450: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
8460: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
8470: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
8480: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
8490: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
84a0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
84b0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
84c0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
84d0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
84e0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
84f0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
8500: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
8510: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
8520: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
8530: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
8540: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
8550: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
8560: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
8570: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
8580: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
8590: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
85a0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
85b0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a to xWrite()..**
85c0: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 .** If xRead() r
85d0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f eturns SQLITE_IO
85e0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 ERR_SHORT_READ i
85f0: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c t must also fill
8600: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 .** in the unrea
8610: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 d portions of th
8620: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 e buffer with ze
8630: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 ros. A VFS that
8640: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 .** fails to zer
8650: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
8660: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f ds might seem to
8670: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c work. However,
8680: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a .** failure to z
8690: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 ero-fill short r
86a0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 eads will eventu
86b0: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 ally lead to.**
86c0: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 database corrupt
86d0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
86e0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
86f0: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 o_methods sqlite
8700: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 3_io_methods;.st
8710: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
8720: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 methods {. int
8730: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 iVersion;. int
8740: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 (*xClose)(sqlite
8750: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
8760: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 (*xRead)(sqlite3
8770: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 _file*, void*, i
8780: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 nt iAmt, sqlite3
8790: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 _int64 iOfst);.
87a0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 int (*xWrite)(s
87b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f qlite3_file*, co
87c0: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 nst void*, int i
87d0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 Amt, sqlite3_int
87e0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 64 iOfst);. int
87f0: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 (*xTruncate)(sq
8800: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c lite3_file*, sql
8810: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 ite3_int64 size)
8820: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 ;. int (*xSync)
8830: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8840: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e int flags);. in
8850: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 t (*xFileSize)(s
8860: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
8870: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 lite3_int64 *pSi
8880: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f ze);. int (*xLo
8890: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
88a0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
88b0: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 *xUnlock)(sqlite
88c0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
88d0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 int (*xCheckRes
88e0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 ervedLock)(sqlit
88f0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 e3_file*, int *p
8900: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 ResOut);. int (
8910: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 *xFileControl)(s
8920: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
8930: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 t op, void *pArg
8940: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 );. int (*xSect
8950: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f orSize)(sqlite3_
8960: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
8970: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
8980: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f istics)(sqlite3_
8990: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 file*);. /* Met
89a0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 hods above are v
89b0: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e alid for version
89c0: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 1 */. int (*xS
89d0: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 hmMap)(sqlite3_f
89e0: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 ile*, int iPg, i
89f0: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f nt pgsz, int, vo
8a00: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a id volatile**);.
8a10: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b int (*xShmLock
8a20: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8a30: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 int offset, int
8a40: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a n, int flags);.
8a50: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 void (*xShmBar
8a60: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 rier)(sqlite3_fi
8a70: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 le*);. int (*xS
8a80: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 hmUnmap)(sqlite3
8a90: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 _file*, int dele
8aa0: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 teFlag);. /* Me
8ab0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
8ac0: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f valid for versio
8ad0: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 n 2 */. int (*x
8ae0: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 Fetch)(sqlite3_f
8af0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
8b00: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 t64 iOfst, int i
8b10: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b Amt, void **pp);
8b20: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 . int (*xUnfetc
8b30: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a h)(sqlite3_file*
8b40: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
8b50: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b iOfst, void *p);
8b60: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 . /* Methods ab
8b70: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f ove are valid fo
8b80: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 r version 3 */.
8b90: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d /* Additional m
8ba0: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 ethods may be ad
8bb0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
8bc0: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a leases */.};../*
8bd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 .** CAPI3REF: St
8be0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 andard File Cont
8bf0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b rol Opcodes.** K
8c00: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 EYWORDS: {file c
8c10: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 ontrol opcodes}
8c20: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 {file control op
8c30: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 code}.**.** Thes
8c40: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
8c50: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 nts are opcodes
8c60: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e for the xFileCon
8c70: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f trol method.** o
8c80: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 f the [sqlite3_i
8c90: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
8ca0: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 t and for the [s
8cb0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
8cc0: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 rol()].** interf
8cd0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ace..**.** <ul>.
8ce0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
8cf0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d FCNTL_LOCKSTATE]
8d00: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
8d10: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
8d20: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
8d30: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 for debugging.
8d40: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 This.** opcode
8d50: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 causes the xFile
8d60: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 Control method t
8d70: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 o write the curr
8d80: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 ent state of.**
8d90: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 the lock (one of
8da0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
8db0: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 NE], [SQLITE_LOC
8dc0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 K_SHARED],.** [S
8dd0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
8de0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f VED], [SQLITE_LO
8df0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 CK_PENDING], or
8e00: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
8e10: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f LUSIVE]).** into
8e20: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 an integer that
8e30: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 the pArg argume
8e40: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 nt points to. Th
8e50: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a is capability.**
8e60: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 is used during
8e70: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f testing and is o
8e80: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 nly available wh
8e90: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 en the SQLITE_TE
8ea0: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 ST.** compile-ti
8eb0: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 me option is use
8ec0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 d..**.** <li>[[S
8ed0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 QLITE_FCNTL_SIZE
8ee0: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b _HINT]].** The [
8ef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a SQLITE_FCNTL_SIZ
8f00: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 E_HINT] opcode i
8f10: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 s used by SQLite
8f20: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 to give the VFS
8f30: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 .** layer a hint
8f40: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 of how large th
8f50: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
8f60: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 will grow to be
8f70: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 during the.** cu
8f80: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f rrent transactio
8f90: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 n. This hint is
8fa0: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 not guaranteed
8fb0: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 to be accurate b
8fc0: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 ut it.** is ofte
8fd0: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e n close. The un
8fe0: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 derlying VFS mig
8ff0: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 ht choose to pre
9000: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 allocate databas
9010: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 e.** file space
9020: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 based on this hi
9030: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 nt in order to h
9040: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 elp writes to th
9050: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 e database.** fi
9060: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a le run faster..*
9070: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9080: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 E_FCNTL_CHUNK_SI
9090: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ZE]].** The [SQL
90a0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f ITE_FCNTL_CHUNK_
90b0: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 SIZE] opcode is
90c0: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 used to request
90d0: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 that the VFS.**
90e0: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e extends and trun
90f0: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 cates the databa
9100: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b se file in chunk
9110: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 s of a size spec
9120: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 ified.** by the
9130: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 user. The fourth
9140: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
9150: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
9160: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a ol()] should .**
9170: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 point to an int
9180: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 eger (type int)
9190: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e containing the n
91a0: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f ew chunk-size to
91b0: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 use.** for the
91c0: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 nominated databa
91d0: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 se. Allocating d
91e0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 atabase file spa
91f0: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 ce in large.** c
9200: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 hunks (say 1MB a
9210: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 t a time), may r
9220: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 educe file-syste
9230: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 m fragmentation
9240: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 and.** improve p
9250: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f erformance on so
9260: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a me systems..**.*
9270: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
9280: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 CNTL_FILE_POINTE
9290: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 R]].** The [SQLI
92a0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
92b0: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 INTER] opcode is
92c0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 used to obtain
92d0: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
92e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
92f0: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 e] object associ
9300: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 ated with a part
9310: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a icular database.
9320: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 ** connection.
9330: 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 See the [sqlite3
9340: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
9350: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 documentation f
9360: 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c or.** additional
9370: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
9380: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
9390: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 _FCNTL_SYNC_OMIT
93a0: 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 TED]].** No long
93b0: 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a er in use..**.**
93c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
93d0: 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 NTL_SYNC]].** Th
93e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
93f0: 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 SYNC] opcode is
9400: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e generated intern
9410: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 ally by SQLite a
9420: 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 nd.** sent to th
9430: 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c e VFS immediatel
9440: 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 y before the xSy
9450: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 nc method is inv
9460: 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 oked on a.** dat
9470: 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 abase file descr
9480: 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 iptor. Or, if th
9490: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 e xSync method i
94a0: 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a s not invoked .*
94b0: 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73 * because the us
94c0: 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 er has configure
94d0: 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a d SQLite with .*
94e0: 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 * [PRAGMA synchr
94f0: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 onous | PRAGMA s
9500: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 ynchronous=OFF]
9510: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e it is invoked in
9520: 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 place .** of th
9530: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 e xSync method.
9540: 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 In most cases, t
9550: 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d he pointer argum
9560: 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a ent passed with.
9570: 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e ** this file-con
9580: 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f trol is NULL. Ho
9590: 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 wever, if the da
95a0: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 tabase file is b
95b0: 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 eing synced.** a
95c0: 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 s part of a mult
95d0: 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 i-database commi
95e0: 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 t, the argument
95f0: 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d points to a nul-
9600: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 terminated.** st
9610: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ring containing
9620: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 the transactions
9630: 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 master-journal
9640: 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 file name. VFSes
9650: 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 that .** do not
9660: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 need this signa
9670: 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c l should silentl
9680: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 y ignore this op
9690: 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f code. Applicatio
96a0: 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f ns .** should no
96b0: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f t call [sqlite3_
96c0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
96d0: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 with this opcode
96e0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 as doing so may
96f0: 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 .** disrupt the
9700: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 operation of th
9710: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 e specialized VF
9720: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 Ses that do requ
9730: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 ire it. .**.**
9740: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
9750: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 TL_COMMIT_PHASET
9760: 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c WO]].** The [SQL
9770: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 ITE_FCNTL_COMMIT
9780: 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 _PHASETWO] opcod
9790: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 e is generated i
97a0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c nternally by SQL
97b0: 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 ite.** and sent
97c0: 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72 to the VFS after
97d0: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 a transaction h
97e0: 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 as been committe
97f0: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a d immediately.**
9800: 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 but before the
9810: 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f database is unlo
9820: 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 cked. VFSes that
9830: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 do not need thi
9840: 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 s signal.** shou
9850: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f ld silently igno
9860: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 re this opcode.
9870: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f Applications sho
9880: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 uld not call.**
9890: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
98a0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 ntrol()] with th
98b0: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 is opcode as doi
98c0: 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 ng so may disrup
98d0: 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 t the .** operat
98e0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 ion of the speci
98f0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 alized VFSes tha
9900: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e t do require it.
9910: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 .**.** <li>[[S
9920: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
9930: 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 2_AV_RETRY]].**
9940: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
9950: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 TL_WIN32_AV_RETR
9960: 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 Y] opcode is use
9970: 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 d to configure a
9980: 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 utomatic.** retr
9990: 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 y counts and int
99a0: 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 ervals for certa
99b0: 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 in disk I/O oper
99c0: 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a ations for the.*
99d0: 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 * windows [VFS]
99e0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 in order to prov
99f0: 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 ide robustness i
9a00: 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f n the presence o
9a10: 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 f.** anti-virus
9a20: 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 programs. By de
9a30: 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f fault, the windo
9a40: 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 ws VFS will retr
9a50: 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 y file read,.**
9a60: 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 file write, and
9a70: 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 file delete oper
9a80: 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 ations up to 10
9a90: 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 times, with a de
9aa0: 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c lay.** of 25 mil
9ab0: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 liseconds before
9ac0: 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 the first retry
9ad0: 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 and with the de
9ae0: 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a lay increasing.*
9af0: 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e * by an addition
9b00: 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e al 25 millisecon
9b10: 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 ds with each sub
9b20: 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 sequent retry.
9b30: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 This.** opcode a
9b40: 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 llows these two
9b50: 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 values (10 retri
9b60: 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 es and 25 millis
9b70: 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 econds of delay)
9b80: 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 .** to be adjust
9b90: 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 ed. The values
9ba0: 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 are changed for
9bb0: 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e all database con
9bc0: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 nections.** with
9bd0: 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 in the same proc
9be0: 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ess. The argume
9bf0: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 nt is a pointer
9c00: 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 to an array of t
9c10: 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 wo.** integers w
9c20: 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 here the first i
9c30: 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 nteger i the new
9c40: 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 retry count and
9c50: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 the second.** i
9c60: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 nteger is the de
9c70: 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 lay. If either
9c80: 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 integer is negat
9c90: 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 ive, then the se
9ca0: 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 tting.** is not
9cb0: 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 changed but inst
9cc0: 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 ead the prior va
9cd0: 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 lue of that sett
9ce0: 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a ing is written.*
9cf0: 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 * into the array
9d00: 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 entry, allowing
9d10: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 the current ret
9d20: 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 ry settings to b
9d30: 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 e.** interrogate
9d40: 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 d. The zDbName
9d50: 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e parameter is ign
9d60: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ored..**.** <li>
9d70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [[SQLITE_FCNTL_P
9d80: 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 ERSIST_WAL]].**
9d90: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
9da0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 TL_PERSIST_WAL]
9db0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
9dc0: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 o set or query t
9dd0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 he.** persistent
9de0: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 [WAL | Write Ah
9df0: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 ead Log] setting
9e00: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 . By default, t
9e10: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 he auxiliary.**
9e20: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 write ahead log
9e30: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 and shared memor
9e40: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 y files used for
9e50: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e transaction con
9e60: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f trol.** are auto
9e70: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 matically delete
9e80: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 d when the lates
9e90: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 t connection to
9ea0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
9eb0: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 closes. Setting
9ec0: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 persistent WAL
9ed0: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 mode causes thos
9ee0: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 e files to persi
9ef0: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 st after.** clos
9f00: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 e. Persisting t
9f10: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 he files is usef
9f20: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 ul when other pr
9f30: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 ocesses that do
9f40: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 not.** have writ
9f50: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 e permission on
9f60: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f the directory co
9f70: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 ntaining the dat
9f80: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a abase file want.
9f90: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 ** to read the d
9fa0: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 atabase file, as
9fb0: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 the WAL and sha
9fc0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 red memory files
9fd0: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 must exist.** i
9fe0: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 n order for the
9ff0: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 database to be r
a000: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f eadable. The fo
a010: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
a020: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 o.** [sqlite3_fi
a030: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f le_control()] fo
a040: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 r this opcode sh
a050: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 ould be a pointe
a060: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e r to an integer.
a070: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 .** That integer
a080: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 is 0 to disable
a090: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 persistent WAL
a0a0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 mode or 1 to ena
a0b0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a ble persistent.*
a0c0: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 * WAL mode. If
a0d0: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d the integer is -
a0e0: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 1, then it is ov
a0f0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 erwritten with t
a100: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 he current.** WA
a110: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 L persistence se
a120: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 tting..**.** <li
a130: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
a140: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
a150: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 ITE]].** ^The [S
a160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 QLITE_FCNTL_POWE
a170: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d RSAFE_OVERWRITE]
a180: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
a190: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 to set or query
a1a0: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e the.** persisten
a1b0: 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 t "powersafe-ove
a1c0: 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 rwrite" or "PSOW
a1d0: 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 " setting. The
a1e0: 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 PSOW setting.**
a1f0: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b determines the [
a200: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 SQLITE_IOCAP_POW
a210: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
a220: 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 ] bit of the.**
a230: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
a240: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 istics methods.
a250: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
a260: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 eter to.** [sqli
a270: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
a280: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 ()] for this opc
a290: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 ode should be a
a2a0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
a2b0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 teger..** That i
a2c0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 nteger is 0 to d
a2d0: 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 isable zero-dama
a2e0: 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 ge mode or 1 to
a2f0: 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 enable zero-dama
a300: 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 ge.** mode. If
a310: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d the integer is -
a320: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 1, then it is ov
a330: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 erwritten with t
a340: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 he current.** ze
a350: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 ro-damage mode s
a360: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c etting..**.** <l
a370: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
a380: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 _OVERWRITE]].**
a390: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
a3a0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 TL_OVERWRITE] op
a3b0: 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 code is invoked
a3c0: 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 by SQLite after
a3d0: 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 opening.** a wri
a3e0: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 te transaction t
a3f0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c o indicate that,
a400: 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f unless it is ro
a410: 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f lled back for so
a420: 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 me.** reason, th
a430: 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 e entire databas
a440: 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f e file will be o
a450: 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 verwritten by th
a460: 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 e current .** tr
a470: 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 ansaction. This
a480: 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 is used by VACUU
a490: 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a M operations..**
a4a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
a4b0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d _FCNTL_VFSNAME]]
a4c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
a4d0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 _FCNTL_VFSNAME]
a4e0: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 opcode can be us
a4f0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 ed to obtain the
a500: 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c names of.** all
a510: 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 [VFSes] in the
a520: 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 VFS stack. The
a530: 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c names are of all
a540: 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 VFS shims and t
a550: 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 he.** final bott
a560: 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 om-level VFS are
a570: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 written into me
a580: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
a590: 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f om .** [sqlite3_
a5a0: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 malloc()] and th
a5b0: 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 e result is stor
a5c0: 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 ed in the char*
a5d0: 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 variable.** that
a5e0: 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
a5f0: 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 meter of [sqlite
a600: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
a610: 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 ] points to..**
a620: 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 The caller is re
a630: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 sponsible for fr
a640: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 eeing the memory
a650: 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 when done. As
a660: 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 with.** all file
a670: 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 -control actions
a680: 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 , there is no gu
a690: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 arantee that thi
a6a0: 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a s will actually.
a6b0: 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 ** do anything.
a6c0: 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 Callers should
a6d0: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 initialize the c
a6e0: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f har* variable to
a6f0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 a NULL.** point
a700: 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 er in case this
a710: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 file-control is
a720: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e not implemented.
a730: 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 This file-cont
a740: 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 rol.** is intend
a750: 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 ed for diagnosti
a760: 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a c use only..**.*
a770: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
a780: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a CNTL_PRAGMA]].**
a790: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 ^Whenever a [PR
a7a0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 AGMA] statement
a7b0: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 is parsed, an [S
a7c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
a7d0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e MA] .** file con
a7e0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 trol is sent to
a7f0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 the open [sqlite
a800: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 3_file] object c
a810: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 orresponding.**
a820: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 to the database
a830: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 file to which th
a840: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 e pragma stateme
a850: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 nt refers. ^The
a860: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 argument.** to t
a870: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
a880: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
a890: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 ntrol is an arra
a8a0: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 y of.** pointers
a8b0: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 to strings (cha
a8c0: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 r**) in which th
a8d0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 e second element
a8e0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a of the array.**
a8f0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
a900: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 the pragma and t
a910: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 he third element
a920: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 is the argument
a930: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d to the.** pragm
a940: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 a or NULL if the
a950: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 pragma has no a
a960: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 rgument. ^The h
a970: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a andler for an.**
a980: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
a990: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 RAGMA] file cont
a9a0: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c rol can optional
a9b0: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 ly make the firs
a9c0: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 t element.** of
a9d0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d the char** argum
a9e0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 ent point to a s
a9f0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 tring obtained f
aa00: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 rom [sqlite3_mpr
aa10: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 intf()].** or th
aa20: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 e equivalent and
aa30: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c that string wil
aa40: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 l become the res
aa50: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d ult of the pragm
aa60: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f a or.** the erro
aa70: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 r message if the
aa80: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e pragma fails. ^
aa90: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 If the.** [SQLIT
aaa0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
aab0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 file control ret
aac0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 urns [SQLITE_NOT
aad0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 FOUND], then nor
aae0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d mal .** [PRAGMA]
aaf0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 processing cont
ab00: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 inues. ^If the
ab10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
ab20: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f AGMA].** file co
ab30: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 ntrol returns [S
ab40: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 QLITE_OK], then
ab50: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d the parser assum
ab60: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 es that the.** V
ab70: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 FS has handled t
ab80: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 he PRAGMA itself
ab90: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 and the parser
aba0: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f generates a no-o
abb0: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 p.** prepared st
abc0: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c atement if resul
abd0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c t string is NULL
abe0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e , or that return
abf0: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 s a copy.** of t
ac00: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 he result string
ac10: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 if the string i
ac20: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e s non-NULL..** ^
ac30: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 If the [SQLITE_F
ac40: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
ac50: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e e control return
ac60: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 s.** any result
ac70: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 code other than
ac80: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b [SQLITE_OK] or [
ac90: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d SQLITE_NOTFOUND]
aca0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 , that means.**
acb0: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 that the VFS enc
acc0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f ountered an erro
acd0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 r while handling
ace0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e the [PRAGMA] an
acf0: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 d the.** compila
ad00: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 tion of the PRAG
ad10: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e MA fails with an
ad20: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 error. ^The [S
ad30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
ad40: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 MA].** file cont
ad50: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 rol occurs at th
ad60: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 e beginning of p
ad70: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 ragma statement
ad80: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a analysis and so.
ad90: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f ** it is able to
ada0: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d override built-
adb0: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 in [PRAGMA] stat
adc0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ements..**.** <l
add0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
ade0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a _BUSYHANDLER]].*
adf0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
ae00: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 CNTL_BUSYHANDLER
ae10: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f ].** file-contro
ae20: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 l may be invoked
ae30: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 by SQLite on th
ae40: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
ae50: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c handle.** shortl
ae60: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 y after it is op
ae70: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f ened in order to
ae80: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f provide a custo
ae90: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 m VFS with acces
aea0: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e s.** to the conn
aeb0: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e ections busy-han
aec0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 dler callback. T
aed0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f he argument is o
aee0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 f type (void **)
aef0: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f .** - an array o
af00: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 f two (void *) v
af10: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 alues. The first
af20: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c (void *) actual
af30: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 ly points.** to
af40: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 a function of ty
af50: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 pe (int (*)(void
af60: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 *)). In order t
af70: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e o invoke the con
af80: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 nections.** busy
af90: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 -handler, this f
afa0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 unction should b
afb0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 e invoked with t
afc0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 he second (void
afd0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 *) in.** the arr
afe0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 ay as the only a
aff0: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 rgument. If it r
b000: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
b010: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 then the operat
b020: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 ion.** should be
b030: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 retried. If it
b040: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 returns zero, th
b050: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f e custom VFS sho
b060: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a uld abandon the.
b070: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 ** current opera
b080: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e tion..**.** <li>
b090: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 [[SQLITE_FCNTL_T
b0a0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a EMPFILENAME]].**
b0b0: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 ^Application ca
b0c0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 n invoke the [SQ
b0d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 LITE_FCNTL_TEMPF
b0e0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f ILENAME] file-co
b0f0: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 ntrol.** to have
b100: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 SQLite generate
b110: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 a.** temporary
b120: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 filename using t
b130: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 he same algorith
b140: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 m that is follow
b150: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a ed to generate.*
b160: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 * temporary file
b170: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 names for TEMP t
b180: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 ables and other
b190: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 internal uses.
b1a0: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 The.** argument
b1b0: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 should be a char
b1c0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 ** which will be
b1d0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
b1e0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 filename.** wri
b1f0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 tten into memory
b200: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
b210: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
b220: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 ]. The caller s
b230: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 hould.** invoke
b240: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
b250: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 on the result t
b260: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 o avoid a memory
b270: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 leak..**.** <li
b280: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
b290: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 MMAP_SIZE]].** T
b2a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
b2b0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 _MMAP_SIZE] file
b2c0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 control is used
b2d0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 to query or set
b2e0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 the.** maximum
b2f0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
b300: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 that will be use
b310: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 d for memory-map
b320: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 ped I/O..** The
b330: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
b340: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 inter to a value
b350: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 of type sqlite3
b360: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 _int64 that.** i
b370: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 s an advisory ma
b380: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
b390: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c bytes in the fil
b3a0: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e e to memory map.
b3b0: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 The.** pointer
b3c0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 is overwritten
b3d0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c with the old val
b3e0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 ue. The limit i
b3f0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 s not changed if
b400: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 .** the value or
b410: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 iginally pointed
b420: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c to is negative,
b430: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 and so the curr
b440: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 ent limit .** ca
b450: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 n be queried by
b460: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 passing in a poi
b470: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 nter to a negati
b480: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 ve number. This
b490: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c .** file-control
b4a0: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 is used interna
b4b0: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 lly to implement
b4c0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 [PRAGMA mmap_si
b4d0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ze]..**.** <li>[
b4e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 [SQLITE_FCNTL_TR
b4f0: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 ACE]].** The [SQ
b500: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 LITE_FCNTL_TRACE
b510: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 ] file control p
b520: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 rovides advisory
b530: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
b540: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 to the VFS about
b550: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 what the higher
b560: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 layers of the S
b570: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 QLite stack are
b580: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 doing..** This f
b590: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 ile control is u
b5a0: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 sed by some VFS
b5b0: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 activity tracing
b5c0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 [shims]..** The
b5d0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a argument is a z
b5e0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
b5f0: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c tring. Higher l
b600: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 ayers in the.**
b610: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 SQLite stack may
b620: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e generate instan
b630: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 ces of this file
b640: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 control if.** t
b650: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 he [SQLITE_USE_F
b660: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 CNTL_TRACE] comp
b670: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
b680: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a is enabled..**.*
b690: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
b6a0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d CNTL_HAS_MOVED]]
b6b0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
b6c0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d FCNTL_HAS_MOVED]
b6d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e file control in
b6e0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 terprets its arg
b6f0: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f ument as a.** po
b700: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
b710: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 ger and it write
b720: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f s a boolean into
b730: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 that integer de
b740: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 pending.** on wh
b750: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
b760: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 file has been r
b770: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f enamed, moved, o
b780: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 r deleted since
b790: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 it.** was first
b7a0: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c opened..**.** <l
b7b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
b7c0: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c _WIN32_SET_HANDL
b7d0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 E]].** The [SQLI
b7e0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 TE_FCNTL_WIN32_S
b7f0: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 ET_HANDLE] opcod
b800: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 e is used for de
b810: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a bugging. This.*
b820: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 * opcode causes
b830: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
b840: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 method to swap
b850: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 the file handle
b860: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 with the one.**
b870: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 pointed to by th
b880: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e e pArg argument.
b890: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 This capabilit
b8a0: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 y is used during
b8b0: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 testing.** and
b8c0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 only needs to be
b8d0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 supported when
b8e0: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 SQLITE_TEST is d
b8f0: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c efined..**.** <l
b900: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
b910: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 _WAL_BLOCK]].**
b920: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
b930: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 L_WAL_BLOCK] is
b940: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 a signal to the
b950: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69 VFS layer that i
b960: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 t might.** be ad
b970: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c vantageous to bl
b980: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 ock on the next
b990: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 WAL lock if the
b9a0: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 lock is not imme
b9b0: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c diately.** avail
b9c0: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73 able. The WAL s
b9d0: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20 ubsystem issues
b9e0: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69 this signal duri
b9f0: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 ng rare.** circu
ba00: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 mstances in orde
ba10: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c r to fix a probl
ba20: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79 em with priority
ba30: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 inversion..** A
ba40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
ba50: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 ld <em>not</em>
ba60: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f use this file-co
ba70: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ntrol..**.** <li
ba80: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
ba90: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 ZIPVFS]].** The
baa0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 [SQLITE_FCNTL_ZI
bab0: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 PVFS] opcode is
bac0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a implemented by z
bad0: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 ipvfs only. All
bae0: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f other.** VFS sho
baf0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 uld return SQLIT
bb00: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 E_NOTFOUND for t
bb10: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a his opcode..**.*
bb20: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
bb30: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 CNTL_RBU]].** Th
bb40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
bb50: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 RBU] opcode is i
bb60: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68 mplemented by th
bb70: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73 e special VFS us
bb80: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 ed by.** the RBU
bb90: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e extension only.
bba0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 All other VFS
bbb0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 should return SQ
bbc0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f LITE_NOTFOUND fo
bbd0: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 r.** this opcode
bbe0: 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a . .** </ul>.*/.
bbf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
bc00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 CNTL_LOCKSTATE
bc10: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 1.#
bc20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
bc30: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 NTL_GET_LOCKPROX
bc40: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 YFILE 2.#d
bc50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
bc60: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TL_SET_LOCKPROXY
bc70: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 FILE 3.#de
bc80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
bc90: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 L_LAST_ERRNO
bca0: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
bcb0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
bcc0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 _SIZE_HINT
bcd0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 5.#defi
bce0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
bcf0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 CHUNK_SIZE
bd00: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 6.#defin
bd10: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 e SQLITE_FCNTL_F
bd20: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 ILE_POINTER
bd30: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 7.#define
bd40: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 SQLITE_FCNTL_SY
bd50: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 NC_OMITTED
bd60: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 8.#define
bd70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
bd80: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 32_AV_RETRY
bd90: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 9.#define S
bda0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 QLITE_FCNTL_PERS
bdb0: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 IST_WAL
bdc0: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 10.#define SQ
bdd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 LITE_FCNTL_OVERW
bde0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 RITE
bdf0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 11.#define SQL
be00: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d ITE_FCNTL_VFSNAM
be10: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
be20: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 12.#define SQLI
be30: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 TE_FCNTL_POWERSA
be40: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 FE_OVERWRITE
be50: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 13.#define SQLIT
be60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 E_FCNTL_PRAGMA
be70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
be80: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
be90: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c _FCNTL_BUSYHANDL
bea0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 ER 15
beb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
bec0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 FCNTL_TEMPFILENA
bed0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a ME 16.
bee0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
bef0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 CNTL_MMAP_SIZE
bf00: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 18.#
bf10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
bf20: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 NTL_TRACE
bf30: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 19.#d
bf40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
bf50: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 TL_HAS_MOVED
bf60: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 20.#de
bf70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
bf80: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 L_SYNC
bf90: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 21.#def
bfa0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
bfb0: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f _COMMIT_PHASETWO
bfc0: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 22.#defi
bfd0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
bfe0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 WIN32_SET_HANDLE
bff0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 23.#defin
c000: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 e SQLITE_FCNTL_W
c010: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 AL_BLOCK
c020: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 24.#define
c030: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 SQLITE_FCNTL_ZI
c040: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 PVFS
c050: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 25.#define
c060: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 SQLITE_FCNTL_RBU
c070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
c080: 20 20 20 20 32 36 0a 0a 2f 2a 20 64 65 70 72 65 26../* depre
c090: 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 cated names */.#
c0a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 define SQLITE_GE
c0b0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
c0c0: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 SQLITE_FCNT
c0d0: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 L_GET_LOCKPROXYF
c0e0: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 ILE.#define SQLI
c0f0: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TE_SET_LOCKPROXY
c100: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 FILE SQLITE
c110: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 _FCNTL_SET_LOCKP
c120: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 ROXYFILE.#define
c130: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 SQLITE_LAST_ERR
c140: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 NO S
c150: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 QLITE_FCNTL_LAST
c160: 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 _ERRNO.../*.** C
c170: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 API3REF: Mutex H
c180: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 andle.**.** The
c190: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 mutex module wit
c1a0: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e hin SQLite defin
c1b0: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 es [sqlite3_mute
c1c0: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 x] to be an.** a
c1d0: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 bstract type for
c1e0: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e a mutex object.
c1f0: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 The SQLite cor
c200: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a e never looks.**
c210: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c at the internal
c220: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
c230: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d of an [sqlite3_m
c240: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a utex]. It only.
c250: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f ** deals with po
c260: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 inters to the [s
c270: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 qlite3_mutex] ob
c280: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 ject..**.** Mute
c290: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 xes are created
c2a0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
c2b0: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a utex_alloc()]..*
c2c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
c2d0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 sqlite3_mutex s
c2e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f qlite3_mutex;../
c2f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
c300: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 S Interface Obje
c310: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 ct.**.** An inst
c320: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 ance of the sqli
c330: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 te3_vfs object d
c340: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
c350: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 face between.**
c360: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 the SQLite core
c370: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 and the underlyi
c380: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ng operating sys
c390: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a tem. The "vfs".
c3a0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f ** in the name o
c3b0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 f the object sta
c3c0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c nds for "virtual
c3d0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 file system".
c3e0: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 See.** the [VFS
c3f0: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 | VFS documentat
c400: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 ion] for further
c410: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
c420: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 .** The value of
c430: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 the iVersion fi
c440: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 eld is initially
c450: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 1 but may be la
c460: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 rger in.** futur
c470: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
c480: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 Lite. Additiona
c490: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 l fields may be
c4a0: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 appended to this
c4b0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 .** object when
c4c0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c the iVersion val
c4d0: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e ue is increased.
c4e0: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 Note that the
c4f0: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 structure.** of
c500: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
c510: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 object changes i
c520: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f n the transactio
c530: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c n between.** SQL
c540: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
c550: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 9 and 3.6.0 and
c560: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e yet the iVersion
c570: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a field was not.*
c580: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a * modified..**.*
c590: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 * The szOsFile f
c5a0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 ield is the size
c5b0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 of the subclass
c5c0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ed [sqlite3_file
c5d0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 ].** structure u
c5e0: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e sed by this VFS.
c5f0: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 mxPathname is
c600: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 the maximum leng
c610: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e th of.** a pathn
c620: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e ame in this VFS.
c630: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 .**.** Registere
c640: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 d sqlite3_vfs ob
c650: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f jects are kept o
c660: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 n a linked list
c670: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 formed by.** the
c680: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 pNext pointer.
c690: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 The [sqlite3_vf
c6a0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a s_register()].**
c6b0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 and [sqlite3_vf
c6c0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 s_unregister()]
c6d0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 interfaces manag
c6e0: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 e this list.** i
c6f0: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 n a thread-safe
c700: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 way. The [sqlit
c710: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 e3_vfs_find()] i
c720: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 nterface.** sear
c730: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 ches the list.
c740: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c Neither the appl
c750: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 ication code nor
c760: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c the VFS.** impl
c770: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c ementation shoul
c780: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 d use the pNext
c790: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 pointer..**.** T
c7a0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 he pNext field i
c7b0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 s the only field
c7c0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f in the sqlite3_
c7d0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 vfs.** structure
c7e0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
c7f0: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 l ever modify.
c800: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 SQLite will only
c810: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f access.** or mo
c820: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 dify this field
c830: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 while holding a
c840: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 particular stati
c850: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 c mutex..** The
c860: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
c870: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 ld never modify
c880: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 anything within
c890: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a the sqlite3_vfs.
c8a0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 ** object once t
c8b0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 he object has be
c8c0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a en registered..*
c8d0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 *.** The zName f
c8e0: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e ield holds the n
c8f0: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d ame of the VFS m
c900: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 odule. The name
c910: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 must.** be uniq
c920: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 ue across all VF
c930: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a S modules..**.**
c940: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 [[sqlite3_vfs.x
c950: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 Open]].** ^SQLit
c960: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 e guarantees tha
c970: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 t the zFilename
c980: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
c990: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 en.** is either
c9a0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f a NULL pointer o
c9b0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 r string obtaine
c9c0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 d.** from xFullP
c9d0: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 athname() with a
c9e0: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 n optional suffi
c9f0: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 x added..** ^If
ca00: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 a suffix is adde
ca10: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 d to the zFilena
ca20: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 me parameter, it
ca30: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 will.** consist
ca40: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 of a single "-"
ca50: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f character follo
ca60: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 wed by no more t
ca70: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e han.** 11 alphan
ca80: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d umeric and/or "-
ca90: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a " characters..**
caa0: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 ^SQLite further
cab0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
cac0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 .** the string w
cad0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 ill be valid and
cae0: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c unchanged until
caf0: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 xClose() is.**
cb00: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 called. Because
cb10: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 of the previous
cb20: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 sentence,.** the
cb30: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
cb40: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 can safely store
cb50: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
cb60: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 e.** filename if
cb70: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d it needs to rem
cb80: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 ember the filena
cb90: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 me for some reas
cba0: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 on..** If the zF
cbb0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
cbc0: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 r to xOpen is a
cbd0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
cbe0: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 n xOpen.** must
cbf0: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 invent its own t
cc00: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f emporary name fo
cc10: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 r the file. ^Wh
cc20: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 enever the .** x
cc30: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
cc40: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 er is NULL it wi
cc50: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 ll also be the c
cc60: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ase that the.**
cc70: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
cc80: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 will include [SQ
cc90: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
cca0: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 ONCLOSE]..**.**
ccb0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
ccc0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e nt to xOpen() in
ccd0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 cludes all bits
cce0: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c set in.** the fl
ccf0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ags argument to
cd00: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
cd10: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c ()]. Or if [sql
cd20: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 ite3_open()].**
cd30: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e or [sqlite3_open
cd40: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 16()] is used, t
cd50: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 hen flags includ
cd60: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b es at least.** [
cd70: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
cd80: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 WRITE] | [SQLITE
cd90: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a _OPEN_CREATE]. .
cda0: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 ** If xOpen() op
cdb0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d ens a file read-
cdc0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 only then it set
cdd0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a s *pOutFlags to.
cde0: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 ** include [SQLI
cdf0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
ce00: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 ]. Other bits i
ce10: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 n *pOutFlags may
ce20: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e be set..**.** ^
ce30: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 (SQLite will als
ce40: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 o add one of the
ce50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 following flags
ce60: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a to the xOpen().
ce70: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 ** call, dependi
ce80: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 ng on the object
ce90: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a being opened:.*
cea0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
ceb0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
cec0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e MAIN_DB].** <li>
ced0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
cee0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 AIN_JOURNAL].**
cef0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
cf00: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c EN_TEMP_DB].** <
cf10: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
cf20: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a N_TEMP_JOURNAL].
cf30: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
cf40: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f _OPEN_TRANSIENT_
cf50: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
cf60: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 LITE_OPEN_SUBJOU
cf70: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
cf80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 SQLITE_OPEN_MAST
cf90: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c ER_JOURNAL].** <
cfa0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
cfb0: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 N_WAL].** </ul>)
cfc0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 ^.**.** The file
cfd0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 I/O implementat
cfe0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 ion can use the
cff0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 object type flag
d000: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 s to.** change t
d010: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 he way it deals
d020: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 with files. For
d030: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 example, an app
d040: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 lication.** that
d050: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 does not care a
d060: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 bout crash recov
d070: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 ery or rollback
d080: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 might make.** th
d090: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 e open of a jour
d0a0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 nal file a no-op
d0b0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 . Writes to thi
d0c0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a s journal would.
d0d0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 ** also be no-op
d0e0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d s, and any attem
d0f0: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a pt to read the j
d100: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 ournal would ret
d110: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f urn.** SQLITE_IO
d120: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 ERR. Or the imp
d130: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 lementation migh
d140: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 t recognize that
d150: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 a database.** f
d160: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e ile will be doin
d170: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 g page-aligned s
d180: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 ector reads and
d190: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 writes in a rand
d1a0: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 om.** order and
d1b0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 set up its I/O s
d1c0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 ubsystem accordi
d1d0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 ngly..**.** SQLi
d1e0: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 te might also ad
d1f0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c d one of the fol
d200: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 lowing flags to
d210: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 the xOpen method
d220: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
d230: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 <li> [SQLITE_OPE
d240: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
d250: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
d260: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d _OPEN_EXCLUSIVE]
d270: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
d280: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
d290: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 _DELETEONCLOSE]
d2a0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 flag means the f
d2b0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a ile should be.**
d2c0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 deleted when it
d2d0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 is closed. ^Th
d2e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 e [SQLITE_OPEN_D
d2f0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a ELETEONCLOSE].**
d300: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 will be set for
d310: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 TEMP databases
d320: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 and their journa
d330: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a ls, transient.**
d340: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 databases, and
d350: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a subjournals..**.
d360: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
d370: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 OPEN_EXCLUSIVE]
d380: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 flag is always u
d390: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 sed in conjuncti
d3a0: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b on.** with the [
d3b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
d3c0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 TE] flag, which
d3d0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c are both directl
d3e0: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 y.** analogous t
d3f0: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 o the O_EXCL and
d400: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f O_CREAT flags o
d410: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e f the POSIX open
d420: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 ().** API. The
d430: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
d440: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e USIVE flag, when
d450: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 paired with the
d460: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e .** SQLITE_OPEN
d470: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 _CREATE, is used
d480: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
d490: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c t file should al
d4a0: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 ways.** be creat
d4b0: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 ed, and that it
d4c0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 is an error if i
d4d0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 t already exists
d4e0: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f ..** It is <i>no
d4f0: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e t</i> used to in
d500: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 dicate the file
d510: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 should be opened
d520: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 .** for exclusi
d530: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a ve access..**.**
d540: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 ^At least szOsF
d550: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d ile bytes of mem
d560: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 ory are allocate
d570: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 d by SQLite.** t
d580: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c o hold the [sql
d590: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 ite3_file] struc
d5a0: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 ture passed as t
d5b0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 he third.** argu
d5c0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 ment to xOpen.
d5d0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 The xOpen method
d5e0: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 does not have t
d5f0: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 o.** allocate th
d600: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 e structure; it
d610: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c should just fill
d620: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 it in. Note th
d630: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 at.** the xOpen
d640: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 method must set
d650: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 the sqlite3_file
d660: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 .pMethods to eit
d670: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b her.** a valid [
d680: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
d690: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f ds] object or to
d6a0: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 NULL. xOpen mu
d6b0: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 st do.** this ev
d6c0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 en if the open f
d6d0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 ails. SQLite ex
d6e0: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 pects that the s
d6f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 qlite3_file.pMet
d700: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 hods.** element
d710: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 will be valid af
d720: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e ter xOpen return
d730: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 s regardless of
d740: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f the success.** o
d750: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 r failure of the
d760: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a xOpen call..**.
d770: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 ** [[sqlite3_vfs
d780: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 .xAccess]].** ^T
d790: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
d7a0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d t to xAccess() m
d7b0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 ay be [SQLITE_AC
d7c0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 CESS_EXISTS].**
d7d0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 to test for the
d7e0: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 existence of a f
d7f0: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f ile, or [SQLITE_
d800: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
d810: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 ] to.** test whe
d820: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 ther a file is r
d830: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 eadable and writ
d840: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 able, or [SQLITE
d850: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a _ACCESS_READ].**
d860: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 to test whether
d870: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 a file is at le
d880: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 ast readable.
d890: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 The file can be
d8a0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a a.** directory..
d8b0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 **.** ^SQLite wi
d8c0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 ll always alloca
d8d0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 te at least mxPa
d8e0: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 thname+1 bytes f
d8f0: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 or the.** output
d900: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 buffer xFullPat
d910: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 hname. The exac
d920: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 t size of the ou
d930: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
d940: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 s also passed as
d950: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 a parameter to
d960: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 both methods. I
d970: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
d980: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 fer.** is not la
d990: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c rge enough, [SQL
d9a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 ITE_CANTOPEN] sh
d9b0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
d9c0: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a . Since this is.
d9d0: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 ** handled as a
d9e0: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 fatal error by S
d9f0: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 QLite, vfs imple
da00: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c mentations shoul
da10: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f d endeavor.** to
da20: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 prevent this by
da30: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e setting mxPathn
da40: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 ame to a suffici
da50: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 ently large valu
da60: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 e..**.** The xRa
da70: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 ndomness(), xSle
da80: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 ep(), xCurrentTi
da90: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 me(), and xCurre
daa0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a ntTimeInt64().**
dab0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
dac0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 not strictly a p
dad0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 art of the files
dae0: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 ystem, but they
daf0: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 are.** included
db00: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 in the VFS struc
db10: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 ture for complet
db20: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 eness..** The xR
db30: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 andomness() func
db40: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f tion attempts to
db50: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 return nBytes b
db60: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d ytes.** of good-
db70: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 quality randomne
db80: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 ss into zOut. T
db90: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
dba0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c is.** the actual
dbb0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
dbc0: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f of randomness o
dbd0: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 btained..** The
dbe0: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 xSleep() method
dbf0: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 causes the calli
dc00: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 ng thread to sle
dc10: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 ep for at.** lea
dc20: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 st the number of
dc30: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 microseconds gi
dc40: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 ven. ^The xCurr
dc50: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 entTime().** met
dc60: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 hod returns a Ju
dc70: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 lian Day Number
dc80: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 for the current
dc90: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 date and time as
dca0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 .** a floating p
dcb0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e oint value..** ^
dcc0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 The xCurrentTime
dcd0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 Int64() method r
dce0: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e eturns, as an in
dcf0: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 teger, the Julia
dd00: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 n.** Day Number
dd10: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 multiplied by 86
dd20: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 400000 (the numb
dd30: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
dd40: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 ds in .** a 24-h
dd50: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e our day). .** ^
dd60: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 SQLite will use
dd70: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 the xCurrentTime
dd80: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 Int64() method t
dd90: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e o get the curren
dda0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 t.** date and ti
ddb0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f me if that metho
ddc0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 d is available (
ddd0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 if iVersion is 2
dde0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 or .** greater
ddf0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e and the function
de00: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
de10: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 NULL) and will f
de20: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 all back.** to x
de30: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 CurrentTime() if
de40: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 xCurrentTimeInt
de50: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 64() is unavaila
de60: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ble..**.** ^The
de70: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 xSetSystemCall()
de80: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c , xGetSystemCall
de90: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 (), and xNestSys
dea0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 temCall() interf
deb0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 aces.** are not
dec0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 used by the SQLi
ded0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 te core. These
dee0: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 optional interfa
def0: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 ces are provided
df00: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 .** by some VFSe
df10: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 s to facilitate
df20: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 testing of the V
df30: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 FS code. By over
df40: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 riding .** syste
df50: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e m calls with fun
df60: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 ctions under its
df70: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 control, a test
df80: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 program can.**
df90: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 simulate faults
dfa0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 and error condit
dfb0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 ions that would
dfc0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 otherwise be dif
dfd0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 ficult.** or imp
dfe0: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 ossible to induc
dff0: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 e. The set of s
e000: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 ystem calls that
e010: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 can be overridd
e020: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f en.** varies fro
e030: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f m one VFS to ano
e040: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f ther, and from o
e050: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 ne version of th
e060: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 e same VFS to th
e070: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c e.** next. Appl
e080: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 ications that us
e090: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 e these interfac
e0a0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 es must be prepa
e0b0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f red for any.** o
e0c0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 r all of these i
e0d0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 nterfaces to be
e0e0: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 NULL or for thei
e0f0: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 r behavior to ch
e100: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 ange.** from one
e110: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 release to the
e120: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 next. Applicati
e130: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 ons must not att
e140: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a empt to access.*
e150: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d * any of these m
e160: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 ethods if the iV
e170: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 ersion of the VF
e180: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 S is less than 3
e190: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
e1a0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 uct sqlite3_vfs
e1b0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 sqlite3_vfs;.typ
e1c0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 edef void (*sqli
e1d0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 te3_syscall_ptr)
e1e0: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 (void);.struct s
e1f0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 qlite3_vfs {. i
e200: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 nt iVersion;
e210: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 /* Struc
e220: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d ture version num
e230: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 ber (currently 3
e240: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 ) */. int szOsF
e250: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 ile;
e260: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c /* Size of subcl
e270: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 assed sqlite3_fi
e280: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 le */. int mxPa
e290: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 thname;
e2a0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 /* Maximum file
e2b0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 pathname length
e2c0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 */. sqlite3_vf
e2d0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f s *pNext; /
e2e0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 * Next registere
e2f0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 d VFS */. const
e300: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 char *zName;
e310: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
e320: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 his virtual file
e330: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 system */. voi
e340: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
e350: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 /* Pointer
e360: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d to application-
e370: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f specific data */
e380: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 . int (*xOpen)(
e390: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
e3a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
e3b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a sqlite3_file*,.
e3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 i
e3d0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 nt flags, int *p
e3e0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 OutFlags);. int
e3f0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 (*xDelete)(sqli
e400: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
e410: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
e420: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 syncDir);. int
e430: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 (*xAccess)(sqli
e440: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
e450: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
e460: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 flags, int *pRe
e470: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sOut);. int (*x
e480: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 FullPathname)(sq
e490: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
e4a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 t char *zName, i
e4b0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a nt nOut, char *z
e4c0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a Out);. void *(*
e4d0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 xDlOpen)(sqlite3
e4e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
e4f0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 r *zFilename);.
e500: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 void (*xDlError
e510: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e520: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 int nByte, char
e530: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 *zErrMsg);. voi
e540: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 d (*(*xDlSym)(sq
e550: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a lite3_vfs*,void*
e560: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 , const char *zS
e570: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 ymbol))(void);.
e580: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 void (*xDlClose
e590: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e5a0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a void*);. int (*
e5b0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c xRandomness)(sql
e5c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e ite3_vfs*, int n
e5d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 Byte, char *zOut
e5e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 );. int (*xSlee
e5f0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c p)(sqlite3_vfs*,
e600: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 int microsecond
e610: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 s);. int (*xCur
e620: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 rentTime)(sqlite
e630: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3_vfs*, double*)
e640: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 ;. int (*xGetLa
e650: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 stError)(sqlite3
e660: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 _vfs*, int, char
e670: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 *);. /*. ** T
e680: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
e690: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 are in version
e6a0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 1 of the sqlite_
e6b0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 vfs object. **
e6c0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f definition. Tho
e6d0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 se that follow a
e6e0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 re added in vers
e6f0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 ion 2 or later.
e700: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 */. int (*xCur
e710: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 rentTimeInt64)(s
e720: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c qlite3_vfs*, sql
e730: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 ite3_int64*);.
e740: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
e750: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
e760: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 versions 1 and
e770: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 2 of the sqlite_
e780: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a vfs object.. **
e790: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 Those below are
e7a0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 for version 3 a
e7b0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f nd greater.. */
e7c0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 . int (*xSetSys
e7d0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 temCall)(sqlite3
e7e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
e7f0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 r *zName, sqlite
e800: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 3_syscall_ptr);.
e810: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c sqlite3_syscal
e820: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 l_ptr (*xGetSyst
e830: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f emCall)(sqlite3_
e840: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
e850: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 *zName);. cons
e860: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 t char *(*xNextS
e870: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 ystemCall)(sqlit
e880: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
e890: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f har *zName);. /
e8a0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
e8b0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
e8c0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 versions 1 throu
e8d0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 gh 3 of the sqli
e8e0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 te_vfs object..
e8f0: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d ** New fields m
e900: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 ay be appended i
e910: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e n figure version
e920: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e s. The iVersion
e930: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c . ** value will
e940: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 increment whene
e950: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 ver this happens
e960: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a . . */.};../*.*
e970: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 * CAPI3REF: Flag
e980: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 s for the xAcces
e990: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a s VFS method.**.
e9a0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 ** These integer
e9b0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 constants can b
e9c0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 e used as the th
e9d0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
e9e0: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 .** the xAccess
e9f0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 method of an [sq
ea00: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
ea10: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 t. They determi
ea20: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 ne.** what kind
ea30: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 of permissions t
ea40: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
ea50: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 d is looking for
ea60: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 ..** With SQLITE
ea70: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 _ACCESS_EXISTS,
ea80: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
ea90: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 od.** simply che
eaa0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
eab0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 file exists..**
eac0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 With SQLITE_ACCE
ead0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 SS_READWRITE, th
eae0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
eaf0: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 .** checks wheth
eb00: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 er the named dir
eb10: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 ectory is both r
eb20: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 eadable and writ
eb30: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 able.** (in othe
eb40: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 r words, if file
eb50: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 s can be added,
eb60: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e removed, and ren
eb70: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 amed within.** t
eb80: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a he directory)..*
eb90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 * The SQLITE_ACC
eba0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f ESS_READWRITE co
ebb0: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e nstant is curren
ebc0: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 tly used only by
ebd0: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 the.** [temp_st
ebe0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
ebf0: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 agma], though th
ec00: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 is could change
ec10: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 in a future.** r
ec20: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
ec30: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 ..** With SQLITE
ec40: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 _ACCESS_READ, th
ec50: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
ec60: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 .** checks wheth
ec70: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 er the file is r
ec80: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 eadable. The SQ
ec90: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
eca0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 constant is.**
ecb0: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 currently unused
ecc0: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 , though it migh
ecd0: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 t be used in a f
ece0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 uture release of
ecf0: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 .** SQLite..*/.#
ed00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
ed10: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 CESS_EXISTS 0
ed20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
ed30: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
ed40: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 1 /* Used by
ed50: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 PRAGMA temp_stor
ed60: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 e_directory */.#
ed70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
ed80: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 CESS_READ 2
ed90: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a /* Unused */.
eda0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
edb0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 Flags for the x
edc0: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 ShmLock VFS meth
edd0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 od.**.** These i
ede0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
edf0: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 define the vari
ee00: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 ous locking oper
ee10: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 ations.** allowe
ee20: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 d by the xShmLoc
ee30: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c k method of [sql
ee40: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
ee50: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 . The.** follow
ee60: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 ing are the only
ee70: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 legal combinati
ee80: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 ons of flags to
ee90: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 the.** xShmLock
eea0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 method:.**.** <u
eeb0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 l>.** <li> SQLI
eec0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 TE_SHM_LOCK | SQ
eed0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a LITE_SHM_SHARED.
eee0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
eef0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 SHM_LOCK | SQLIT
ef00: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a E_SHM_EXCLUSIVE.
ef10: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
ef20: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c SHM_UNLOCK | SQL
ef30: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a ITE_SHM_SHARED.*
ef40: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
ef50: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 HM_UNLOCK | SQLI
ef60: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
ef70: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
ef80: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 When unlocking,
ef90: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 the same SHARED
efa0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 or EXCLUSIVE fla
efb0: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 g must be suppli
efc0: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 ed as.** was giv
efd0: 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 en on the corres
efe0: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a ponding lock. .
eff0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f **.** The xShmLo
f000: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 ck method can tr
f010: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e ansition between
f020: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 unlocked and SH
f030: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 ARED or.** betwe
f040: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 en unlocked and
f050: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 EXCLUSIVE. It c
f060: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e annot transition
f070: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a between SHARED.
f080: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 ** and EXCLUSIVE
f090: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
f0a0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 ITE_SHM_UNLOCK
f0b0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
f0c0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 QLITE_SHM_LOCK
f0d0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
f0e0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 SQLITE_SHM_SHAR
f0f0: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 ED 4.#defi
f100: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 ne SQLITE_SHM_EX
f110: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a CLUSIVE 8../*
f120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 .** CAPI3REF: Ma
f130: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 ximum xShmLock i
f140: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ndex.**.** The x
f150: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f ShmLock method o
f160: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 n [sqlite3_io_me
f170: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 thods] may use v
f180: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e alues.** between
f190: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 0 and this uppe
f1a0: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 r bound as its "
f1b0: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 offset" argument
f1c0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 ..** The SQLite
f1d0: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 core will never
f1e0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 attempt to acqui
f1f0: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a re or release a.
f200: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 ** lock outside
f210: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f of this range.*/
f220: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
f230: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 SHM_NLOCK
f240: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 8.../*.** CAPI3
f250: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 REF: Initialize
f260: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 The SQLite Libra
f270: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ry.**.** ^The sq
f280: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f290: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 () routine initi
f2a0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 alizes the.** SQ
f2b0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e Lite library. ^
f2c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 The sqlite3_shut
f2d0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a down() routine.*
f2e0: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e * deallocates an
f2f0: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 y resources that
f300: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 were allocated
f310: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 by sqlite3_initi
f320: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 alize()..** Thes
f330: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 e routines are d
f340: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 esigned to aid i
f350: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 n process initia
f360: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 lization and.**
f370: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 shutdown on embe
f380: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 dded systems. W
f390: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 orkstation appli
f3a0: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a cations using.**
f3b0: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 SQLite normally
f3c0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 do not need to
f3d0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 invoke either of
f3e0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
f3f0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f .**.** A call to
f400: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
f410: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 ize() is an "eff
f420: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 ective" call if
f430: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 it is.** the fir
f440: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f st time sqlite3_
f450: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
f460: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 invoked during t
f470: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a he lifetime of.*
f480: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f * the process, o
f490: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 r if it is the f
f4a0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 irst time sqlite
f4b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
f4c0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c s invoked.** fol
f4d0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f lowing a call to
f4e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
f4f0: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 n(). ^(Only an
f500: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a effective call.*
f510: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 * of sqlite3_ini
f520: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 tialize() does a
f530: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ny initializatio
f540: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 n. All other ca
f550: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c lls.** are harml
f560: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a ess no-ops.)^.**
f570: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 .** A call to sq
f580: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f590: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 is an "effectiv
f5a0: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 e" call if it is
f5b0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 the first.** ca
f5c0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
f5d0: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 utdown() since t
f5e0: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f he last sqlite3_
f5f0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e initialize(). ^
f600: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 (Only.** an effe
f610: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 ctive call to sq
f620: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f630: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 does any deinit
f640: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 ialization..** A
f650: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 ll other valid c
f660: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
f670: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 shutdown() are h
f680: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 armless no-ops.)
f690: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ^.**.** The sqli
f6a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
f6b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 interface is th
f6c0: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 readsafe, but sq
f6d0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f6e0: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 .** is not. The
f6f0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
f700: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 n() interface mu
f710: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 st only be calle
f720: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 d from a.** sing
f730: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 le thread. All
f740: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 open [database c
f750: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 onnections] must
f760: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 be closed and a
f770: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 ll.** other SQLi
f780: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 te resources mus
f790: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 t be deallocated
f7a0: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 prior to invoki
f7b0: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 ng.** sqlite3_sh
f7c0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 utdown()..**.**
f7d0: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e Among other thin
f7e0: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 gs, ^sqlite3_ini
f7f0: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 tialize() will i
f800: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
f810: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d _os_init(). Sim
f820: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 ilarly, ^sqlite3
f830: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 _shutdown().** w
f840: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 ill invoke sqlit
f850: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a e3_os_end()..**.
f860: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
f870: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
f880: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 tine returns [SQ
f890: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
f8a0: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 ess..** ^If for
f8b0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c some reason, sql
f8c0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
f8d0: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 ) is unable to i
f8e0: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 nitialize.** the
f8f0: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 library (perhap
f900: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 s it is unable t
f910: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 o allocate a nee
f920: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 ded resource suc
f930: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 h.** as a mutex)
f940: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b it returns an [
f950: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 error code] othe
f960: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f r than [SQLITE_O
f970: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 K]..**.** ^The s
f980: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
f990: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 e() routine is c
f9a0: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 alled internally
f9b0: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a by many other.*
f9c0: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 * SQLite interfa
f9d0: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 ces so that an a
f9e0: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c pplication usual
f9f0: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ly does not need
fa00: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 to.** invoke sq
fa10: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
fa20: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f () directly. Fo
fa30: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 r example, [sqli
fa40: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 te3_open()].** c
fa50: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 alls sqlite3_ini
fa60: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 tialize() so the
fa70: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 SQLite library
fa80: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 will be automati
fa90: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c cally.** initial
faa0: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 ized when [sqlit
fab0: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 e3_open()] is ca
fac0: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e lled if it has n
fad0: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 ot be initialize
fae0: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e d.** already. ^
faf0: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 However, if SQLi
fb00: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
fb10: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
fb20: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a OMIT_AUTOINIT].*
fb30: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f * compile-time o
fb40: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ption, then the
fb50: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 automatic calls
fb60: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 to sqlite3_initi
fb70: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f alize().** are o
fb80: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 mitted and the a
fb90: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
fba0: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 call sqlite3_ini
fbb0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 tialize() direct
fbc0: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 ly.** prior to u
fbd0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 sing any other S
fbe0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
fbf0: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f For maximum po
fc00: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 rtability,.** it
fc10: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
fc20: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
fc30: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 s always invoke
fc40: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
fc50: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 ze().** directly
fc60: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 prior to using
fc70: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 any other SQLite
fc80: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 interface. Fut
fc90: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 ure releases.**
fca0: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 of SQLite may re
fcb0: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 quire this. In
fcc0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
fcd0: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 behavior exhibi
fce0: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 ted.** when SQLi
fcf0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
fd00: 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 ith [SQLITE_OMIT
fd10: 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 _AUTOINIT] might
fd20: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 become the.** d
fd30: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 efault behavior
fd40: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 in some future r
fd50: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
fd60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
fd70: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f te3_os_init() ro
fd80: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 utine does opera
fd90: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 ting-system spec
fda0: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 ific.** initiali
fdb0: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 zation of the SQ
fdc0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 Lite library. T
fdd0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e he sqlite3_os_en
fde0: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 d().** routine u
fdf0: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 ndoes the effect
fe00: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 of sqlite3_os_i
fe10: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 nit(). Typical
fe20: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d tasks.** perform
fe30: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 ed by these rout
fe40: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c ines include all
fe50: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c ocation or deall
fe60: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 ocation.** of st
fe70: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 atic resources,
fe80: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f initialization o
fe90: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c f global variabl
fea0: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 es,.** setting u
feb0: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c p a default [sql
fec0: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 ite3_vfs] module
fed0: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a , or setting up.
fee0: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e ** a default con
fef0: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 figuration using
ff00: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
ff10: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 ()]..**.** The a
ff20: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
ff30: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 d never invoke e
ff40: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 ither sqlite3_os
ff50: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 _init().** or sq
ff60: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 lite3_os_end() d
ff70: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 irectly. The ap
ff80: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
ff90: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 only invoke.**
ffa0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
ffb0: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 ze() and sqlite3
ffc0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 _shutdown(). Th
ffd0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 e sqlite3_os_ini
ffe0: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 t().** interface
fff0: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d is called autom
10000 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 atically by sqli
10010 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
10020 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f and.** sqlite3_
10030 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c os_end() is call
10040 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 ed by sqlite3_sh
10050 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f utdown(). Appro
10060 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d priate.** implem
10070 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 entations for sq
10080 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
10090 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 and sqlite3_os_e
100a0 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c nd().** are buil
100b0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 t into SQLite wh
100c0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 en it is compile
100d0 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 d for Unix, Wind
100e0 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a ows, or OS/2..**
100f0 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 When [custom bu
10100 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 ilds | built for
10110 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 other platforms
10120 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 ].** (using the
10130 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 [SQLITE_OS_OTHER
10140 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =1] compile-time
10150 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 .** option) the
10160 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
10170 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 supply a suitab
10180 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
10190 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 n for.** sqlite3
101a0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 _os_init() and s
101b0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e qlite3_os_end().
101c0 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e An application
101d0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 -supplied.** imp
101e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
101f0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
10200 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 or sqlite3_os_e
10210 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 nd().** must ret
10220 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
10230 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 on success and s
10240 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 ome other [error
10250 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 code] upon.** f
10260 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 ailure..*/.SQLIT
10270 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
10280 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
10290 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 _initialize(void
102a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
102b0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
102c0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
102d0 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f n(void);.SQLITE_
102e0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
102f0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f TDCALL sqlite3_o
10300 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 s_init(void);.SQ
10310 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
10320 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
10330 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 te3_os_end(void)
10340 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
10350 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 F: Configuring T
10360 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
10370 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 y.**.** The sqli
10380 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 te3_config() int
10390 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
103a0 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f o make global co
103b0 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 nfiguration.** c
103c0 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 hanges to SQLite
103d0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e in order to tun
103e0 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 e SQLite to the
103f0 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f specific needs o
10400 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 f.** the applica
10410 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 tion. The defau
10420 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e lt configuration
10430 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
10440 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c for most.** appl
10450 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 ications and so
10460 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
10470 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 usually not nece
10480 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a ssary. It is.**
10490 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 provided to sup
104a0 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 port rare applic
104b0 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 ations with unus
104c0 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ual needs..**.**
104d0 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f <b>The sqlite3_
104e0 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
104f0 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 ce is not thread
10500 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 safe. The applic
10510 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e ation.** must en
10520 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 sure that no oth
10530 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
10540 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 aces are invoked
10550 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 by other.** thr
10560 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 eads while sqlit
10570 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 e3_config() is r
10580 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a unning.</b>.**.*
10590 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
105a0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
105b0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 .** may only be
105c0 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f invoked prior to
105d0 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c library initial
105e0 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a ization using.**
105f0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
10600 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 lize()] or after
10610 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 shutdown by [sq
10620 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
10630 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 ]..** ^If sqlite
10640 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 3_config() is ca
10650 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 lled after [sqli
10660 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
10670 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 ] and before.**
10680 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
10690 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c n()] then it wil
106a0 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f l return SQLITE_
106b0 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c MISUSE..** Note,
106c0 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e however, that ^
106d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
106e0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 can be called a
106f0 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a s part of the.**
10700 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
10710 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f of an applicatio
10720 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 n-defined [sqlit
10730 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a e3_os_init()]..*
10740 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
10750 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
10760 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 e3_config() is a
10770 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f n integer.** [co
10780 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
10790 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 on] that determi
107a0 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 nes.** what prop
107b0 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 erty of SQLite i
107c0 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 s to be configur
107d0 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 ed. Subsequent
107e0 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 arguments.** var
107f0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 y depending on t
10800 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f he [configuratio
10810 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 n option].** in
10820 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
10830 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 nt..**.** ^When
10840 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 a configuration
10850 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 option is set, s
10860 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
10870 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
10880 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 OK]..** ^If the
10890 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 option is unknow
108a0 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 n or SQLite is u
108b0 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 nable to set the
108c0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 option.** then
108d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 this routine ret
108e0 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 urns a non-zero
108f0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f [error code]..*/
10900 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
10910 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c SQLITE_CDECL sql
10920 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c ite3_config(int,
10930 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
10940 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
10950 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
10960 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 ctions.** METHOD
10970 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
10980 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 The sqlite3_db_c
10990 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
109a0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b e is used to mak
109b0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a e configuration.
109c0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 ** changes to a
109d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
109e0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 tion]. The inte
109f0 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 rface is similar
10a00 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
10a10 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 config()] except
10a20 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 that the change
10a30 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e s apply to a sin
10a40 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 gle.** [database
10a50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 connection] (sp
10a60 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 ecified in the f
10a70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a irst argument)..
10a80 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
10a90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
10aa0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 ite3_db_config(D
10ab0 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a ,V,...) is the.
10ac0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e ** [SQLITE_DBCON
10ad0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 FIG_LOOKASIDE |
10ae0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 configuration ve
10af0 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 rb] - an integer
10b00 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 code .** that i
10b10 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 ndicates what as
10b20 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 pect of the [dat
10b30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
10b40 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 ] is being confi
10b50 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 gured..** Subseq
10b60 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 uent arguments v
10b70 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ary depending on
10b80 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
10b90 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e on verb..**.** ^
10ba0 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 Calls to sqlite3
10bb0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 _db_config() ret
10bc0 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 urn SQLITE_OK if
10bd0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
10be0 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 the call is cons
10bf0 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 idered successfu
10c00 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 l..*/.SQLITE_API
10c10 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 int SQLITE_CDEC
10c20 4c 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e L sqlite3_db_con
10c30 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e fig(sqlite3*, in
10c40 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a t op, ...);../*.
10c50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
10c60 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 ory Allocation R
10c70 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e outines.**.** An
10c80 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
10c90 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 s object defines
10ca0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 the interface b
10cb0 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a etween SQLite.**
10cc0 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d and low-level m
10cd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
10ce0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
10cf0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 This object is
10d00 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 used in only one
10d10 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 place in the SQ
10d20 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a Lite interface..
10d30 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** A pointer to
10d40 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
10d50 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 his object is th
10d60 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a e argument to.**
10d70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
10d80 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e ()] when the con
10d90 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
10da0 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f n is.** [SQLITE_
10db0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f CONFIG_MALLOC] o
10dc0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 r [SQLITE_CONFIG
10dd0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a _GETMALLOC]. .*
10de0 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e * By creating an
10df0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
10e00 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 s object.** and
10e10 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 passing it to [s
10e20 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b qlite3_config]([
10e30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
10e40 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 LLOC]).** during
10e50 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 configuration,
10e60 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 an application c
10e70 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c an specify an al
10e80 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d ternative.** mem
10e90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
10ea0 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c ubsystem for SQL
10eb0 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 ite to use for a
10ec0 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e ll of its.** dyn
10ed0 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 amic memory need
10ee0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 s..**.** Note th
10ef0 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 at SQLite comes
10f00 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 with several [bu
10f10 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c ilt-in memory al
10f20 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 locators].** tha
10f30 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 t are perfectly
10f40 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 adequate for the
10f50 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 overwhelming ma
10f60 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 jority of applic
10f70 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 ations.** and th
10f80 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 at this object i
10f90 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f s only useful to
10fa0 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 a tiny minority
10fb0 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 of applications
10fc0 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c .** with special
10fd0 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ized memory allo
10fe0 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 cation requireme
10ff0 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 nts. This objec
11000 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 t is.** also use
11010 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 d during testing
11020 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 of SQLite in or
11030 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 der to specify a
11040 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a n alternative.**
11050 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
11060 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 r that simulates
11070 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d memory out-of-m
11080 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 emory conditions
11090 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 in.** order to
110a0 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 verify that SQLi
110b0 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 te recovers grac
110c0 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 efully from such
110d0 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a .** conditions..
110e0 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f **.** The xMallo
110f0 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 c, xRealloc, and
11100 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d xFree methods m
11110 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 ust work like th
11120 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 e.** malloc(), r
11130 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 ealloc() and fre
11140 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 e() functions fr
11150 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 om the standard
11160 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 C library..** ^S
11170 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 QLite guarantees
11180 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 that the second
11190 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
111a0 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 xRealloc is alwa
111b0 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 ys a value retur
111c0 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 ned by a prior c
111d0 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e all to xRoundup.
111e0 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f .**.** xSize sho
111f0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 uld return the a
11200 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 llocated size of
11210 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
11220 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 tion.** previous
11230 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ly obtained from
11240 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 xMalloc or xRea
11250 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 lloc. The alloc
11260 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 ated size.** is
11270 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 always at least
11280 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 as big as the re
11290 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 quested size but
112a0 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a may be larger..
112b0 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 **.** The xRound
112c0 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e up method return
112d0 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 s what would be
112e0 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 the allocated si
112f0 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 ze of.** a memor
11300 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 y allocation giv
11310 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 en a particular
11320 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 requested size.
11330 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 Most memory.**
11340 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 allocators round
11350 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 up memory alloc
11360 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 ations at least
11370 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 to the next mult
11380 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 iple.** of 8. S
11390 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 ome allocators r
113a0 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 ound up to a lar
113b0 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 ger multiple or
113c0 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e to a power of 2.
113d0 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 .** Every memory
113e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 allocation requ
113f0 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 est coming in th
11400 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d rough [sqlite3_m
11410 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b alloc()].** or [
11420 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
11430 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 )] first calls x
11440 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f Roundup. If xRo
11450 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c undup returns 0,
11460 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 .** that causes
11470 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
11480 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ng memory alloca
11490 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a tion to fail..**
114a0 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 .** The xInit me
114b0 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 thod initializes
114c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
114d0 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d cator. For exam
114e0 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 ple,.** it might
114f0 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 allocate any re
11500 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 quire mutexes or
11510 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 initialize inte
11520 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 rnal data.** str
11530 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 uctures. The xS
11540 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 hutdown method i
11550 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 s invoked (indir
11560 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 ectly) by.** [sq
11570 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
11580 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 ] and should dea
11590 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f llocate any reso
115a0 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a urces acquired.*
115b0 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 * by xInit. The
115c0 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 pAppData pointe
115d0 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 r is used as the
115e0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 only parameter
115f0 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 to.** xInit and
11600 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a xShutdown..**.**
11610 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 SQLite holds th
11620 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f e [SQLITE_MUTEX_
11630 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d STATIC_MASTER] m
11640 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 utex when it inv
11650 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 okes.** the xIni
11660 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 t method, so the
11670 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 xInit method ne
11680 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 ed not be thread
11690 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 safe. The.** xS
116a0 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 hutdown method i
116b0 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 s only called fr
116c0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 om [sqlite3_shut
116d0 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f down()] so it do
116e0 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 es.** not need t
116f0 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 o be threadsafe
11700 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c either. For all
11710 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 other methods,
11720 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 SQLite.** holds
11730 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 the [SQLITE_MUTE
11740 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 X_STATIC_MEM] mu
11750 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 tex as long as t
11760 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f he.** [SQLITE_CO
11770 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 NFIG_MEMSTATUS]
11780 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
11790 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f tion is turned o
117a0 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 n (which.** it i
117b0 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e s by default) an
117c0 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 d so the methods
117d0 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c are automatical
117e0 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a ly serialized..*
117f0 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 * However, if [S
11800 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
11810 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 STATUS] is disab
11820 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 led, then the ot
11830 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d her.** methods m
11840 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 ust be threadsaf
11850 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 e or else make t
11860 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 heir own arrange
11870 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 ments for.** ser
11880 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a ialization..**.*
11890 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 * SQLite will ne
118a0 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 ver invoke xInit
118b0 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 () more than onc
118c0 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 e without an int
118d0 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c ervening.** call
118e0 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e to xShutdown().
118f0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
11900 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d ct sqlite3_mem_m
11910 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d ethods sqlite3_m
11920 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 em_methods;.stru
11930 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d ct sqlite3_mem_m
11940 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 ethods {. void
11950 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 *(*xMalloc)(int)
11960 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d ; /* Mem
11970 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
11980 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 unction */. voi
11990 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a d (*xFree)(void*
119a0 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 ); /* F
119b0 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f ree a prior allo
119c0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 cation */. void
119d0 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f *(*xRealloc)(vo
119e0 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 id*,int); /* Re
119f0 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 size an allocati
11a00 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 on */. int (*xS
11a10 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 ize)(void*);
11a20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e /* Return
11a30 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 the size of an
11a40 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
11a50 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 int (*xRoundup)(
11a60 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f int); /
11a70 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 * Round up reque
11a80 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 st size to alloc
11a90 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 ation size */.
11aa0 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 int (*xInit)(voi
11ab0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f d*); /
11ac0 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 * Initialize the
11ad0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
11ae0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 r */. void (*xS
11af0 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b hutdown)(void*);
11b00 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 /* Deiniti
11b10 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 alize the memory
11b20 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 allocator */.
11b30 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 void *pAppData;
11b40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
11b50 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 * Argument to xI
11b60 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 nit() and xShutd
11b70 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a own() */.};../*.
11b80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
11b90 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f figuration Optio
11ba0 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ns.** KEYWORDS:
11bb0 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f {configuration o
11bc0 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 ption}.**.** The
11bd0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
11be0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 the available i
11bf0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 nteger configura
11c00 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 tion options tha
11c10 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 t.** can be pass
11c20 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
11c30 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
11c40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
11c50 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
11c60 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 .** New configur
11c70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 ation options ma
11c80 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
11c90 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
11ca0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 SQLite..** Exis
11cb0 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 ting configurati
11cc0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 on options might
11cd0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 be discontinued
11ce0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a . Applications.
11cf0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 ** should check
11d00 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 the return code
11d10 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f from [sqlite3_co
11d20 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 nfig()] to make
11d30 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 sure that.** the
11d40 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 call worked. T
11d50 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 he [sqlite3_conf
11d60 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ig()] interface
11d70 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a will return a.**
11d80 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 non-zero [error
11d90 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 code] if a disc
11da0 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 ontinued or unsu
11db0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 pported configur
11dc0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 ation option.**
11dd0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a is invoked..**.*
11de0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 * <dl>.** [[SQLI
11df0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
11e00 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c THREAD]] <dt>SQL
11e10 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
11e20 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 ETHREAD</dt>.**
11e30 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f <dd>There are no
11e40 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
11e50 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 is option. ^Thi
11e60 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 s option sets th
11e70 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 e.** [threading
11e80 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d mode] to Single-
11e90 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 thread. In othe
11ea0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 r words, it disa
11eb0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 bles.** all mute
11ec0 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 xing and puts SQ
11ed0 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 Lite into a mode
11ee0 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e where it can on
11ef0 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 ly be used.** by
11f00 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 a single thread
11f10 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 . ^If SQLite i
11f20 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
11f30 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
11f40 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
11f50 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
11f60 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
11f70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 tion then.** it
11f80 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 is not possible
11f90 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 to change the [t
11fa0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 hreading mode] f
11fb0 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a rom its default.
11fc0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 ** value of Sing
11fd0 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f le-thread and so
11fe0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
11ff0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ()] will return
12000 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f .** [SQLITE_ERRO
12010 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 R] if called wit
12020 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e h the SQLITE_CON
12030 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
12040 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f .** configuratio
12050 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a n option.</dd>.*
12060 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
12070 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
12080 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
12090 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
120a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
120b0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
120c0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
120d0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f on. ^This optio
120e0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 n sets the.** [t
120f0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 hreading mode] t
12100 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 o Multi-thread.
12110 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
12120 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 it disables.**
12130 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 mutexing on [dat
12140 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
12150 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
12160 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 statement] objec
12170 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 ts..** The appli
12180 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e cation is respon
12190 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c sible for serial
121a0 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a izing access to.
121b0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
121c0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 nections] and [p
121d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
121e0 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 ts]. But other
121f0 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 mutexes.** are e
12200 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 nabled so that S
12210 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 QLite will be sa
12220 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d fe to use in a m
12230 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a ulti-threaded.**
12240 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 environment as
12250 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 long as no two t
12260 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 hreads attempt t
12270 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a o use the same.*
12280 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
12290 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 ection] at the s
122a0 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 ame time. ^If S
122b0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
122c0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 d with.** the [S
122d0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
122e0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 | SQLITE_THREAD
122f0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d SAFE=0] compile-
12300 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e time option then
12310 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f .** it is not po
12320 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 ssible to set th
12330 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b e Multi-thread [
12340 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
12350 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
12360 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 config()] will r
12370 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 eturn [SQLITE_ER
12380 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 ROR] if called w
12390 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 ith the.** SQLIT
123a0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
123b0 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 READ configurati
123c0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a on option.</dd>.
123d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
123e0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
123f0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
12400 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c NFIG_SERIALIZED<
12410 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 /dt>.** <dd>Ther
12420 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e e are no argumen
12430 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
12440 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e n. ^This option
12450 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 sets the.** [th
12460 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f reading mode] to
12470 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 Serialized. In
12480 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 other words, thi
12490 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 s option enables
124a0 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 .** all mutexes
124b0 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 including the re
124c0 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 cursive.** mutex
124d0 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 es on [database
124e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 connection] and
124f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
12500 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a ent] objects..**
12510 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 In this mode (w
12520 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 hich is the defa
12530 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 ult when SQLite
12540 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
12550 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 .** [SQLITE_THRE
12560 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 ADSAFE=1]) the S
12570 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 QLite library wi
12580 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c ll itself serial
12590 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f ize access.** to
125a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
125b0 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 ctions] and [pre
125c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
125d0 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a ] so that the.**
125e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 application is
125f0 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 free to use the
12600 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 same [database c
12610 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 onnection] or th
12620 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 e.** same [prepa
12630 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
12640 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 n different thre
12650 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 ads at the same
12660 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c time..** ^If SQL
12670 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
12680 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
12690 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
126a0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
126b0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
126c0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
126d0 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 * it is not poss
126e0 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 ible to set the
126f0 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 Serialized [thre
12700 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a ading mode] and.
12710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
12720 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ig()] will retur
12730 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
12740 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 if called with
12750 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f the.** SQLITE_CO
12760 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 NFIG_SERIALIZED
12770 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
12780 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tion.</dd>.**.**
12790 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
127a0 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 _MALLOC]] <dt>SQ
127b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
127c0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 OC</dt>.** <dd>
127d0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
127e0 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f FIG_MALLOC optio
127f0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
12800 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
12810 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 is .** a pointer
12820 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
12830 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
12840 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
12850 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 ucture..** The a
12860 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 rgument specifie
12870 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 s.** alternative
12880 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 low-level memor
12890 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
128a0 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 tines to be used
128b0 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 in place of.**
128c0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
128d0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 ation routines b
128e0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 uilt into SQLite
128f0 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 .)^ ^SQLite make
12900 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 s.** its own pri
12910 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 vate copy of the
12920 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
12930 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
12940 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a hods] structure.
12950 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 ** before the [s
12960 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
12970 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f call returns.</
12980 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
12990 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
129a0 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 LOC]] <dt>SQLITE
129b0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
129c0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e C</dt>.** <dd> ^
129d0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
129e0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 IG_GETMALLOC opt
129f0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
12a00 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
12a10 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 h.** is a pointe
12a20 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
12a30 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
12a40 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 _mem_methods] st
12a50 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 ructure..** The
12a60 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
12a70 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 hods].** structu
12a80 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 re is filled wit
12a90 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 h the currently
12aa0 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 defined memory a
12ab0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
12ac0 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 es.)^.** This op
12ad0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 tion can be used
12ae0 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 to overload the
12af0 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 default memory
12b00 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f allocation.** ro
12b10 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 utines with a wr
12b20 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c apper that simul
12b30 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c ations memory al
12b40 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 location failure
12b50 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 or.** tracks me
12b60 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 mory usage, for
12b70 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a example. </dd>.*
12b80 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
12b90 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d NFIG_MEMSTATUS]]
12ba0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
12bb0 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 IG_MEMSTATUS</dt
12bc0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 >.** <dd> ^The S
12bd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
12be0 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 STATUS option ta
12bf0 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d kes single argum
12c00 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c ent of type int,
12c10 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 .** interpreted
12c20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 as a boolean, wh
12c30 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 ich enables or d
12c40 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c isables the coll
12c50 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d ection of.** mem
12c60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
12c70 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 tatistics. ^(Whe
12c80 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
12c90 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 ion statistics a
12ca0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 re.** disabled,
12cb0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 the following SQ
12cc0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
12cd0 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 become non-opera
12ce0 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c tional:.** <ul
12cf0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c >.** <li> [sql
12d00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
12d10 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
12d20 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
12d30 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 ghwater()].**
12d40 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f <li> [sqlite3_so
12d50 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 ft_heap_limit64(
12d60 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
12d70 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 lite3_status64()
12d80 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a ].** </ul>)^.*
12d90 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 * ^Memory alloca
12da0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 tion statistics
12db0 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 are enabled by d
12dc0 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 efault unless SQ
12dd0 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 Lite is.** compi
12de0 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 led with [SQLITE
12df0 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 _DEFAULT_MEMSTAT
12e00 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 US]=0 in which c
12e10 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c ase memory.** al
12e20 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 location statist
12e30 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 ics are disabled
12e40 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 by default..**
12e50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
12e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
12e70 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 TCH]] <dt>SQLITE
12e80 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c _CONFIG_SCRATCH<
12e90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
12ea0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
12eb0 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 SCRATCH option s
12ec0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 pecifies a stati
12ed0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a c memory buffer.
12ee0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 ** that SQLite c
12ef0 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 an use for scrat
12f00 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 ch memory. ^(Th
12f10 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
12f20 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 guments.** to SQ
12f30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
12f40 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 TCH: A pointer
12f50 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 an 8-byte.** ali
12f60 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 gned memory buff
12f70 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 er from which th
12f80 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 e scratch alloca
12f90 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a tions will be.**
12fa0 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 drawn, the size
12fb0 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 of each scratch
12fc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 allocation (sz)
12fd0 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 ,.** and the max
12fe0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 imum number of s
12ff0 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f cratch allocatio
13000 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 ns (N).)^.** The
13010 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
13020 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 must be a pointe
13030 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 r to an 8-byte a
13040 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a ligned buffer.**
13050 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a of at least sz*
13060 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 N bytes of memor
13070 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 y..** ^SQLite wi
13080 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 ll not use more
13090 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 than one scratch
130a0 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 buffers per thr
130b0 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ead..** ^SQLite
130c0 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 will never reque
130d0 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66 st a scratch buf
130e0 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 fer that is more
130f0 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 than 6.** times
13100 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 the database pa
13110 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 ge size..** ^If
13120 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 SQLite needs nee
13130 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a ds additional.**
13140 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 scratch memory
13150 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 beyond what is p
13160 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 rovided by this
13170 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
13180 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b tion, then .** [
13190 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
131a0 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 ] will be used t
131b0 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d o obtain the mem
131c0 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a ory needed.<p>.*
131d0 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c * ^When the appl
131e0 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 ication provides
131f0 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 any amount of s
13200 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 cratch memory us
13210 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f ing.** SQLITE_CO
13220 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 NFIG_SCRATCH, SQ
13230 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 Lite avoids unne
13240 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a cessary large.**
13250 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
13260 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e |heap allocation
13270 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 s]..** This can
13280 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f help [Robson pro
13290 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 of|prevent memor
132a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
132b0 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 lures] due to he
132c0 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 ap.** fragmentat
132d0 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 ion in low-memor
132e0 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 y embedded syste
132f0 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a ms..** </dd>.**.
13300 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
13310 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c IG_PAGECACHE]] <
13320 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
13330 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a _PAGECACHE</dt>.
13340 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c ** <dd> ^The SQL
13350 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
13360 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 ACHE option spec
13370 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d ifies a static m
13380 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 emory buffer.**
13390 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 that SQLite can
133a0 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 use for the data
133b0 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 base page cache
133c0 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 with the default
133d0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 page.** cache i
133e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 mplementation.
133f0 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 .** This configu
13400 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f ration should no
13410 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 t be used if an
13420 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
13430 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 ne page.** cache
13440 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
13450 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 is loaded using
13460 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 the [SQLITE_CONF
13470 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20 63 IG_PCACHE2].** c
13480 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
13490 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 ion..** ^There a
134a0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e re three argumen
134b0 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e ts to SQLITE_CON
134c0 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 FIG_PAGECACHE: A
134d0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 pointer to.** 8
134e0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a -byte aligned.**
134f0 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a memory, the siz
13500 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 e of each page b
13510 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 uffer (sz), and
13520 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 the number of pa
13530 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 ges (N)..** The
13540 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 sz argument shou
13550 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f ld be the size o
13560 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 f the largest da
13570 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 tabase page.** (
13580 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 a power of two b
13590 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 etween 512 and 6
135a0 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 5536) plus some
135b0 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 extra bytes for
135c0 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 each.** page hea
135d0 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 der. ^The numbe
135e0 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 r of extra bytes
135f0 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70 needed by the p
13600 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 age header.** ca
13610 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 n be determined
13620 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 using the [SQLIT
13630 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f E_CONFIG_PCACHE_
13640 48 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a 2a HDRSZ] option .*
13650 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f * to [sqlite3_co
13660 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74 20 nfig()]..** ^It
13670 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 is harmless, apa
13680 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 rt from the wast
13690 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f ed memory,.** fo
136a0 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 r the sz paramet
136b0 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 er to be larger
136c0 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 than necessary.
136d0 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 The first.** ar
136e0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f gument should po
136f0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 inter to an 8-by
13700 74 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b te aligned block
13710 20 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74 0a of memory that.
13720 2a 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20 73 ** is at least s
13730 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d z*N bytes of mem
13740 6f 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20 73 ory, otherwise s
13750 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 ubsequent behavi
13760 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e or is.** undefin
13770 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 ed..** ^SQLite w
13780 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f ill use the memo
13790 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 ry provided by t
137a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
137b0 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 t to satisfy its
137c0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 .** memory needs
137d0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e for the first N
137e0 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 pages that it a
137f0 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e dds to cache. ^
13800 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a If additional.**
13810 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f page cache memo
13820 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 ry is needed bey
13830 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 ond what is prov
13840 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 ided by this opt
13850 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c ion, then.** SQL
13860 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c ite goes to [sql
13870 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 ite3_malloc()] f
13880 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 or the additiona
13890 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e l storage space.
138a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
138b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
138c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
138d0 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a NFIG_HEAP</dt>.*
138e0 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 * <dd> ^The SQLI
138f0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f TE_CONFIG_HEAP o
13900 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 ption specifies
13910 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 a static memory
13920 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 buffer .** that
13930 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 SQLite will use
13940 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 for all of its d
13950 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c ynamic memory al
13960 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a location needs.*
13970 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 * beyond those p
13980 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b rovided for by [
13990 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
139a0 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 RATCH] and.** [S
139b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
139c0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 ECACHE]..** ^The
139d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 SQLITE_CONFIG_H
139e0 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e EAP option is on
139f0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
13a00 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
13a10 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 ed.** with eithe
13a20 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 r [SQLITE_ENABLE
13a30 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 _MEMSYS3] or [SQ
13a40 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 LITE_ENABLE_MEMS
13a50 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 YS5] and returns
13a60 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f .** [SQLITE_ERRO
13a70 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 R] if invoked ot
13a80 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 herwise..** ^The
13a90 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
13aa0 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 uments to SQLITE
13ab0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a _CONFIG_HEAP:.**
13ac0 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e An 8-byte align
13ad0 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 ed pointer to th
13ae0 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 e memory,.** the
13af0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
13b00 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 in the memory b
13b10 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d uffer, and the m
13b20 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f inimum allocatio
13b30 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 n size..** ^If t
13b40 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 he first pointer
13b50 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 (the memory poi
13b60 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 nter) is NULL, t
13b70 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 hen SQLite rever
13b80 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 ts.** to using i
13b90 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 ts default memor
13ba0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 y allocator (the
13bb0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 system malloc()
13bc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 implementation)
13bd0 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 ,.** undoing any
13be0 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f prior invocatio
13bf0 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e n of [SQLITE_CON
13c00 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 FIG_MALLOC]. ^I
13c10 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 f the.** memory
13c20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e pointer is not N
13c30 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 ULL then the alt
13c40 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a ernative memory.
13c50 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 ** allocator is
13c60 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c engaged to handl
13c70 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 e all of SQLites
13c80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
13c90 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 on needs..** The
13ca0 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 first pointer (
13cb0 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 the memory point
13cc0 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 er) must be alig
13cd0 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 ned to an 8-byte
13ce0 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 .** boundary or
13cf0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 subsequent behav
13d00 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 ior of SQLite wi
13d10 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e ll be undefined.
13d20 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 .** The minimum
13d30 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 allocation size
13d40 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a is capped at 2**
13d50 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 12. Reasonable v
13d60 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 alues.** for the
13d70 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 minimum allocat
13d80 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a ion size are 2**
13d90 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 5 through 2**8.<
13da0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
13db0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
13dc0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
13dd0 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a NFIG_MUTEX</dt>.
13de0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
13df0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
13e00 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 X option takes a
13e10 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
13e20 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 which is a.** p
13e30 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
13e40 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 tance of the [sq
13e50 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
13e60 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a ods] structure..
13e70 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 ** The argument
13e80 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e specifies altern
13e90 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 ative low-level
13ea0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 mutex routines t
13eb0 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 o be used.** in
13ec0 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 place the mutex
13ed0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 routines built i
13ee0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e nto SQLite.)^ ^
13ef0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 SQLite makes a c
13f00 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f opy of.** the co
13f10 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 ntent of the [sq
13f20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
13f30 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 ods] structure b
13f40 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 efore the call t
13f50 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
13f60 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e nfig()] returns.
13f70 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
13f80 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
13f90 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
13fa0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
13fb0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
13fc0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
13fd0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e n then.** the en
13fe0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 tire mutexing su
13ff0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 bsystem is omitt
14000 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c ed from the buil
14010 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c d and hence call
14020 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s to.** [sqlite3
14030 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 _config()] with
14040 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 the SQLITE_CONFI
14050 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 G_MUTEX configur
14060 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c ation option wil
14070 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c l.** return [SQL
14080 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e ITE_ERROR].</dd>
14090 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
140a0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d CONFIG_GETMUTEX]
140b0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
140c0 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 FIG_GETMUTEX</dt
140d0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 >.** <dd> ^(The
140e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
140f0 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 TMUTEX option ta
14100 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
14110 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 ument which.** i
14120 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
14130 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
14140 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
14150 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
14160 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 ure. The.** [sq
14170 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
14180 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 ods].** structur
14190 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 e is filled with
141a0 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 the currently d
141b0 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 efined mutex rou
141c0 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 tines.)^.** This
141d0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 option can be u
141e0 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 sed to overload
141f0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 the default mute
14200 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 x allocation.**
14210 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 routines with a
14220 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 wrapper used to
14230 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 track mutex usag
14240 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 e for performanc
14250 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f e.** profiling o
14260 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 r testing, for e
14270 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 xample. ^If SQ
14280 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
14290 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
142a0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
142b0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
142c0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
142d0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
142e0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 ** the entire mu
142f0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d texing subsystem
14300 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d is omitted from
14310 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 the build and h
14320 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a ence calls to.**
14330 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
14340 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c ()] with the SQL
14350 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
14360 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f TEX configuratio
14370 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a n option will.**
14380 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
14390 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a ERROR].</dd>.**.
143a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
143b0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c IG_LOOKASIDE]] <
143c0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
143d0 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a _LOOKASIDE</dt>.
143e0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
143f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
14400 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b ASIDE option tak
14410 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 es two arguments
14420 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a that determine.
14430 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 ** the default s
14440 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 ize of lookaside
14450 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 memory on each
14460 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
14470 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 tion]..** The fi
14480 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
14490 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
144a0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 ach lookaside bu
144b0 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 ffer slot and th
144c0 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 e second is the
144d0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f number of.** slo
144e0 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 ts allocated to
144f0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f each database co
14500 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 nnection.)^ ^(S
14510 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
14520 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 KASIDE.** sets t
14530 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 he <i>default</i
14540 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 > lookaside size
14550 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 . The [SQLITE_DB
14560 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
14570 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b ].** option to [
14580 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
14590 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 g()] can be used
145a0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c to change the l
145b0 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 ookaside.** conf
145c0 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 iguration on ind
145d0 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 ividual connecti
145e0 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a ons.)^ </dd>.**.
145f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
14600 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 IG_PCACHE2]] <dt
14610 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
14620 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c CACHE2</dt>.** <
14630 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 dd> ^(The SQLITE
14640 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 _CONFIG_PCACHE2
14650 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
14660 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
14670 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f hich is .** a po
14680 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c inter to an [sql
14690 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
146a0 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 ods2] object. T
146b0 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 his object speci
146c0 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 fies.** the inte
146d0 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f rface to a custo
146e0 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 m page cache imp
146f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a lementation.)^.*
14700 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 * ^SQLite makes
14710 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 a copy of the [s
14720 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
14730 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c thods2] object.<
14740 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
14750 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
14760 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 ACHE2]] <dt>SQLI
14770 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
14780 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 CHE2</dt>.** <dd
14790 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 > ^(The SQLITE_C
147a0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
147b0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
147c0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
147d0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f which.** is a po
147e0 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c inter to an [sql
147f0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
14800 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 ods2] object. S
14810 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a QLite copies of.
14820 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 ** the current p
14830 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d age cache implem
14840 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 entation into th
14850 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 at object.)^ </d
14860 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
14870 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c E_CONFIG_LOG]] <
14880 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
14890 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 _LOG</dt>.** <dd
148a0 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e > The SQLITE_CON
148b0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 FIG_LOG option i
148c0 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 s used to config
148d0 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a ure the SQLite.*
148e0 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 * global [error
148f0 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 log]..** (^The S
14900 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
14910 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 option takes tw
14920 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 o arguments: a p
14930 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 ointer to a.** f
14940 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 unction with a c
14950 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 all signature of
14960 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 void(*)(void*,i
14970 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c nt,const char*),
14980 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 .** and a point
14990 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 er to void. ^If
149a0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 the function poi
149b0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c nter is not NULL
149c0 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b , it is.** invok
149d0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c ed by [sqlite3_l
149e0 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 og()] to process
149f0 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 each logging ev
14a00 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a ent. ^If the.**
14a10 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 function pointe
14a20 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b r is NULL, the [
14a30 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 sqlite3_log()] i
14a40 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 nterface becomes
14a50 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 a no-op..** ^Th
14a60 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 e void pointer t
14a70 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e hat is the secon
14a80 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 d argument to SQ
14a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
14aa0 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 is.** passed thr
14ab0 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 ough as the firs
14ac0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 t parameter to t
14ad0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
14ae0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a efined logger.**
14af0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 function whenev
14b00 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e er that function
14b10 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 is invoked. ^T
14b20 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
14b30 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f ter to.** the lo
14b40 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 gger function is
14b50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 a copy of the f
14b60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
14b70 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 o the correspond
14b80 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
14b90 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 log()] call and
14ba0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 is intended to b
14bb0 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 e a [result code
14bc0 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 ] or an.** [exte
14bd0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
14be0 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 ]. ^The third p
14bf0 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 arameter passed
14c00 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 to the logger is
14c10 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 .** log message
14c20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 after formatting
14c30 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e via [sqlite3_sn
14c40 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 printf()]..** Th
14c50 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 e SQLite logging
14c60 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f interface is no
14c70 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 t reentrant; the
14c80 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e logger function
14c90 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 .** supplied by
14ca0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
14cb0 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 must not invoke
14cc0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 any SQLite inter
14cd0 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 face..** In a mu
14ce0 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 lti-threaded app
14cf0 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 lication, the ap
14d00 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
14d10 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 d logger.** func
14d20 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 tion must be thr
14d30 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a eadsafe. </dd>.*
14d40 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
14d50 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 NFIG_URI]] <dt>S
14d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
14d70 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 .** <dd>^(The SQ
14d80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 LITE_CONFIG_URI
14d90 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
14da0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f ingle argument o
14db0 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 f type int..** I
14dc0 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e f non-zero, then
14dd0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 URI handling is
14de0 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 globally enable
14df0 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 d. If the parame
14e00 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 ter is zero,.**
14e10 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e then URI handlin
14e20 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 g is globally di
14e30 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 sabled.)^ ^If UR
14e40 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c I handling is gl
14e50 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 obally.** enable
14e60 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 d, all filenames
14e70 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 passed to [sqli
14e80 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
14e90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
14ea0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ,.** [sqlite3_op
14eb0 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 en16()] or.** sp
14ec0 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 ecified as part
14ed0 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d of [ATTACH] comm
14ee0 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 ands are interpr
14ef0 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 eted as URIs, re
14f00 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 gardless.** of w
14f10 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
14f20 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 e [SQLITE_OPEN_U
14f30 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 RI] flag is set
14f40 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 when the databas
14f50 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e.** connection
14f60 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 is opened. ^If i
14f70 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 t is globally di
14f80 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 sabled, filename
14f90 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e s are.** only in
14fa0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 terpreted as URI
14fb0 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f s if the SQLITE_
14fc0 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 OPEN_URI flag is
14fd0 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a set when the.**
14fe0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
14ff0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 tion is opened.
15000 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 ^(By default, UR
15010 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c I handling is gl
15020 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c obally.** disabl
15030 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 ed. The default
15040 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 value may be cha
15050 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e nged by compilin
15060 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 g with the.** [S
15070 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 QLITE_USE_URI] s
15080 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e ymbol defined.)^
15090 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
150a0 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f CONFIG_COVERING_
150b0 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 INDEX_SCAN]] <dt
150c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 >SQLITE_CONFIG_C
150d0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 OVERING_INDEX_SC
150e0 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 AN.** <dd>^The S
150f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 QLITE_CONFIG_COV
15100 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e ERING_INDEX_SCAN
15110 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
15120 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a single integer.*
15130 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 * argument which
15140 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
15150 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 as a boolean in
15160 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 order to enable
15170 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 or disable.** th
15180 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e e use of coverin
15190 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 g indices for fu
151a0 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 ll table scans i
151b0 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 n the query opti
151c0 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 mizer..** ^The d
151d0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 efault setting i
151e0 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 s determined.**
151f0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 by the [SQLITE_A
15200 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e LLOW_COVERING_IN
15210 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c DEX_SCAN] compil
15220 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f e-time option, o
15230 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 r is "on".** if
15240 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d that compile-tim
15250 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 e option is omit
15260 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c ted..** The abil
15270 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 ity to disable t
15280 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 he use of coveri
15290 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 ng indices for f
152a0 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a ull table scans.
152b0 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f ** is because so
152c0 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 me incorrectly c
152d0 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c oded legacy appl
152e0 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d ications might m
152f0 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 alfunction.** wh
15300 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 en the optimizat
15310 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 ion is enabled.
15320 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 Providing the a
15330 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 bility to.** dis
15340 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a able the optimiz
15350 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 ation allows the
15360 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 older, buggy ap
15370 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 plication code t
15380 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 o work.** withou
15390 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 t change even wi
153a0 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e th newer version
153b0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a s of SQLite..**.
153c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
153d0 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 IG_PCACHE]] [[SQ
153e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
153f0 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 CACHE]].** <dt>S
15400 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
15410 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 CHE and SQLITE_C
15420 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a ONFIG_GETPCACHE.
15430 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 ** <dd> These op
15440 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 tions are obsole
15450 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f te and should no
15460 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 t be used by new
15470 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 code..** They a
15480 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 re retained for
15490 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
154a0 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 ibility but are
154b0 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c now no-ops..** <
154c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
154d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f ITE_CONFIG_SQLLO
154e0 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 G]].** <dt>SQLIT
154f0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a E_CONFIG_SQLLOG.
15500 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
15510 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c on is only avail
15520 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 able if sqlite i
15530 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
15540 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 the.** [SQLITE_E
15550 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 NABLE_SQLLOG] pr
15560 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 e-processor macr
15570 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 o defined. The f
15580 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 irst argument sh
15590 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 ould.** be a poi
155a0 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 nter to a functi
155b0 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 on of type void(
155c0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 *)(void*,sqlite3
155d0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 *,const char*, i
155e0 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f nt)..** The seco
155f0 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 nd should be of
15600 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 type (void*). Th
15610 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e e callback is in
15620 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 voked by the lib
15630 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 rary.** in three
15640 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d separate circum
15650 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 stances, identif
15660 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 ied by the value
15670 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a passed as the.*
15680 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 * fourth paramet
15690 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 er. If the fourt
156a0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 h parameter is 0
156b0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 , then the datab
156c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
156d0 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 * passed as the
156e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
156f0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 has just been op
15700 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 ened. The third
15710 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e argument.** poin
15720 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 ts to a buffer c
15730 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 ontaining the na
15740 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 me of the main d
15750 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 atabase file. If
15760 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 the.** fourth p
15770 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 arameter is 1, t
15780 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 hen the SQL stat
15790 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 ement that the t
157a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a hird parameter.*
157b0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 * points to has
157c0 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 just been execut
157d0 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 ed. Or, if the f
157e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
157f0 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 is 2, then.** th
15800 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 e connection bei
15810 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 ng passed as the
15820 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
15830 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 r is being close
15840 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 d. The.** third
15850 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 parameter is pas
15860 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 sed NULL In this
15870 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 case. An examp
15880 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 le of using this
15890 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f .** configuratio
158a0 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 n option can be
158b0 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 seen in the "tes
158c0 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 t_sqllog.c" sour
158d0 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 ce file in.** th
158e0 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 e canonical SQLi
158f0 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c te source tree.<
15900 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
15910 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f ITE_CONFIG_MMAP_
15920 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 SIZE]].** <dt>SQ
15930 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 LITE_CONFIG_MMAP
15940 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 _SIZE.** <dd>^SQ
15950 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 LITE_CONFIG_MMAP
15960 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 _SIZE takes two
15970 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 64-bit integer (
15980 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 sqlite3_int64) v
15990 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 alues.** that ar
159a0 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d e the default mm
159b0 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 ap size limit (t
159c0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 he default setti
159d0 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d ng for.** [PRAGM
159e0 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e A mmap_size]) an
159f0 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c d the maximum al
15a00 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 lowed mmap size
15a10 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 limit..** ^The d
15a20 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 efault setting c
15a30 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e an be overridden
15a40 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73 by each databas
15a50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 e connection usi
15a60 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 ng.** either the
15a70 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 [PRAGMA mmap_si
15a80 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 ze] command, or
15a90 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 by using the.**
15aa0 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d [SQLITE_FCNTL_MM
15ab0 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f AP_SIZE] file co
15ac0 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 ntrol. ^(The ma
15ad0 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d ximum allowed mm
15ae0 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 ap size.** will
15af0 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e be silently trun
15b00 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 cated if necessa
15b10 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f ry so that it do
15b20 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 es not exceed th
15b30 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d e.** compile-tim
15b40 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 e maximum mmap s
15b50 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a ize set by the.*
15b60 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d * [SQLITE_MAX_MM
15b70 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 AP_SIZE] compile
15b80 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a -time option.)^.
15b90 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 ** ^If either ar
15ba0 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f gument to this o
15bb0 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 ption is negativ
15bc0 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 e, then that arg
15bd0 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e ument is.** chan
15be0 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 ged to its compi
15bf0 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e le-time default.
15c00 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
15c10 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 CONFIG_WIN32_HEA
15c20 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 PSIZE]].** <dt>S
15c30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e QLITE_CONFIG_WIN
15c40 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 32_HEAPSIZE.** <
15c50 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 dd>^The SQLITE_C
15c60 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 ONFIG_WIN32_HEAP
15c70 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f SIZE option is o
15c80 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
15c90 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f SQLite is.** co
15ca0 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f mpiled for Windo
15cb0 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ws with the [SQL
15cc0 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 ITE_WIN32_MALLOC
15cd0 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 ] pre-processor
15ce0 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 macro.** defined
15cf0 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 . ^SQLITE_CONFIG
15d00 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 _WIN32_HEAPSIZE
15d10 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 takes a 32-bit u
15d20 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 nsigned integer
15d30 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 value.** that sp
15d40 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 ecifies the maxi
15d50 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 mum size of the
15d60 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a created heap..**
15d70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
15d80 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a FIG_PCACHE_HDRSZ
15d90 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
15da0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 _CONFIG_PCACHE_H
15db0 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 DRSZ.** <dd>^The
15dc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
15dd0 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 CACHE_HDRSZ opti
15de0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
15df0 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 e parameter whic
15e00 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 h.** is a pointe
15e10 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
15e20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 and writes into
15e30 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 that integer the
15e40 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 number of extra
15e50 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 .** bytes per pa
15e60 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 ge required for
15e70 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 each page in [SQ
15e80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
15e90 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 CACHE]..** The a
15ea0 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 mount of extra s
15eb0 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61 pace required ca
15ec0 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 n change dependi
15ed0 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c ng on the compil
15ee0 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c er,.** target pl
15ef0 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 atform, and SQLi
15f00 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a te version..**.*
15f10 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
15f20 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 G_PMASZ]].** <dt
15f30 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
15f40 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 MASZ.** <dd>^The
15f50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
15f60 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 MASZ option take
15f70 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d s a single param
15f80 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 eter which.** is
15f90 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 an unsigned int
15fa0 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 eger and sets th
15fb0 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 e "Minimum PMA S
15fc0 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c ize" for the mul
15fd0 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f tithreaded.** so
15fe0 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 rter to that int
15ff0 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 eger. The defau
16000 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 lt minimum PMA S
16010 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68 ize is set by th
16020 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 e.** [SQLITE_SOR
16030 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 TER_PMASZ] compi
16040 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 le-time option.
16050 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65 New threads are
16060 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 launched.** to
16070 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f help with sort o
16080 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d perations when m
16090 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 ultithreaded sor
160a0 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c ting.** is enabl
160b0 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 ed (using the [P
160c0 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 RAGMA threads] c
160d0 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 ommand) and the
160e0 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e amount of conten
160f0 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 t.** to be sorte
16100 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61 d exceeds the pa
16110 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 ge size times th
16120 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 e minimum of the
16130 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 .** [PRAGMA cach
16140 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 e_size] setting
16150 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a and this value..
16160 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
16170 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
16180 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 G_SINGLETHREAD
16190 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 1 /* nil */.#de
161a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
161b0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 IG_MULTITHREAD
161c0 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 2 /* nil */.#d
161d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
161e0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 FIG_SERIALIZED
161f0 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 3 /* nil */.#
16200 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
16210 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 NFIG_MALLOC
16220 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 4 /* sqlite3
16230 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f _mem_methods* */
16240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16250 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
16260 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 5 /* sqlit
16270 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 e3_mem_methods*
16280 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16290 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
162a0 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 6 /* voi
162b0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 d*, int sz, int
162c0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c N */.#define SQL
162d0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
162e0 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 ACHE 7 /* v
162f0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e oid*, int sz, in
16300 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 t N */.#define S
16310 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
16320 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a P 8 /*
16330 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 void*, int nByt
16340 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 e, int min */.#d
16350 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
16360 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 FIG_MEMSTATUS
16370 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 9 /* boolean
16380 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16390 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 E_CONFIG_MUTEX
163a0 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 10 /* sql
163b0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
163c0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
163d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
163e0 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a MUTEX 11 /*
163f0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
16400 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 ethods* */./* pr
16410 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f eviously SQLITE_
16420 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f CONFIG_CHUNKALLO
16430 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f C 12 which is no
16440 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 w unused. */ .#d
16450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
16460 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 FIG_LOOKASIDE
16470 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 13 /* int int
16480 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16490 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 E_CONFIG_PCACHE
164a0 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 14 /* no-
164b0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 op */.#define SQ
164c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
164d0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 CACHE 15 /*
164e0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 no-op */.#define
164f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
16500 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 OG 16
16510 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 /* xFunc, void*
16520 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16530 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 E_CONFIG_URI
16540 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 17 /* int
16550 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16560 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
16570 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 2 18 /* sq
16580 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
16590 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e hods2* */.#defin
165a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
165b0 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 GETPCACHE2 19
165c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 /* sqlite3_pcac
165d0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a he_methods2* */.
165e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
165f0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 ONFIG_COVERING_I
16600 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a NDEX_SCAN 20 /*
16610 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
16620 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 SQLITE_CONFIG_SQ
16630 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f LLOG 21 /
16640 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a * xSqllog, void*
16650 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16660 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 TE_CONFIG_MMAP_S
16670 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 IZE 22 /* sq
16680 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c lite3_int64, sql
16690 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 ite3_int64 */.#d
166a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
166b0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 FIG_WIN32_HEAPSI
166c0 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 ZE 23 /* i
166d0 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 nt nByte */.#def
166e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
166f0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 G_PCACHE_HDRSZ
16700 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 24 /* int
16710 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 *psz */.#define
16720 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
16730 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 MASZ
16740 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 25 /* unsign
16750 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a ed int szPma */.
16760 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
16770 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
16780 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 tion Configurati
16790 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a on Options.**.**
167a0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
167b0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 are the availab
167c0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 le integer confi
167d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
167e0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 that.** can be
167f0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 passed as the se
16800 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
16810 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 the [sqlite3_db
16820 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
16830 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 face..**.** New
16840 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
16850 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 tions may be add
16860 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
16870 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
16880 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e .** Existing con
16890 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
168a0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 ns might be disc
168b0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 ontinued. Appli
168c0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
168d0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 d check the retu
168e0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 rn code from [sq
168f0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
16900 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 )] to make sure
16910 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c that.** the call
16920 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b worked. ^The [
16930 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
16940 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 g()] interface w
16950 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 ill return a.**
16960 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
16970 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f code] if a disco
16980 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 ntinued or unsup
16990 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 ported configura
169a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 tion option.** i
169b0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a s invoked..**.**
169c0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c <dl>.** <dt>SQL
169d0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
169e0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c KASIDE</dt>.** <
169f0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
16a00 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 takes three add
16a10 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
16a20 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 s that determine
16a30 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 the .** [lookas
16a40 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ide memory alloc
16a50 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 ator] configurat
16a60 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 ion for the [dat
16a70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
16a80 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 ]..** ^The first
16a90 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 argument (the t
16aa0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
16ab0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f o [sqlite3_db_co
16ac0 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 nfig()] is a.**
16ad0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d pointer to a mem
16ae0 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 ory buffer to us
16af0 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 e for lookaside
16b00 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 memory..** ^The
16b10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 first argument a
16b20 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f fter the SQLITE_
16b30 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
16b40 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 DE verb.** may b
16b50 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 e NULL in which
16b60 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c case SQLite will
16b70 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a allocate the.**
16b80 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 lookaside buffe
16b90 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b r itself using [
16ba0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
16bb0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 ]. ^The second a
16bc0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
16bd0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c * size of each l
16be0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 ookaside buffer
16bf0 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 slot. ^The thir
16c00 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
16c10 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 e number of.** s
16c20 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 lots. The size
16c30 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e of the buffer in
16c40 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
16c50 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 ent must be grea
16c60 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 ter than.** or e
16c70 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 qual to the prod
16c80 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e uct of the secon
16c90 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 d and third argu
16ca0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 ments. The buff
16cb0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c er.** must be al
16cc0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 igned to an 8-by
16cd0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 te boundary. ^I
16ce0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 f the second arg
16cf0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 ument to.** SQLI
16d00 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
16d10 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d ASIDE is not a m
16d20 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 ultiple of 8, it
16d30 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a is internally.*
16d40 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 * rounded down t
16d50 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c o the next small
16d60 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 er multiple of 8
16d70 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 . ^(The lookasi
16d80 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e de memory.** con
16d90 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 figuration for a
16da0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
16db0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 tion can only be
16dc0 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 changed when th
16dd0 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e at.** connection
16de0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
16df0 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 y using lookasid
16e00 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 e memory, or in
16e10 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 other words.** w
16e20 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 hen the "current
16e30 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 value" returned
16e40 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
16e50 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 db_status](D,[SQ
16e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
16e70 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a ASIDE],...) is z
16e80 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 ero..** Any atte
16e90 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 mpt to change th
16ea0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f e lookaside memo
16eb0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ry configuration
16ec0 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a when lookaside.
16ed0 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 ** memory is in
16ee0 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 use leaves the c
16ef0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 onfiguration unc
16f00 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 hanged and retur
16f10 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 ns .** [SQLITE_B
16f20 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a USY].)^</dd>.**.
16f30 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ** <dt>SQLITE_DB
16f40 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b CONFIG_ENABLE_FK
16f50 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 EY</dt>.** <dd>
16f60 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 ^This option is
16f70 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f used to enable o
16f80 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e r disable the en
16f90 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 forcement of.**
16fa0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e [foreign key con
16fb0 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 straints]. Ther
16fc0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 e should be two
16fd0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
16fe0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 ents..** The fir
16ff0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 st argument is a
17000 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 n integer which
17010 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
17020 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a FK enforcement,.
17030 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 ** positive to e
17040 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 nable FK enforce
17050 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 ment or negative
17060 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 to leave FK enf
17070 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 orcement.** unch
17080 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f anged. The seco
17090 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
170a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
170b0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 integer into whi
170c0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e ch.** is written
170d0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 0 or 1 to indic
170e0 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 ate whether FK e
170f0 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 nforcement is of
17100 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f f or on.** follo
17110 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 wing this call.
17120 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
17130 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e meter may be a N
17140 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a ULL pointer, in.
17150 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 ** which case th
17160 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 e FK enforcement
17170 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 setting is not
17180 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c reported back. <
17190 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
171a0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
171b0 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 NABLE_TRIGGER</d
171c0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
171d0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 option is used
171e0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 to enable or dis
171f0 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 able [CREATE TRI
17200 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d GGER | triggers]
17210 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c ..** There shoul
17220 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f d be two additio
17230 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a nal arguments..*
17240 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
17250 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 ment is an integ
17260 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f er which is 0 to
17270 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 disable trigger
17280 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 s,.** positive t
17290 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 o enable trigger
172a0 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f s or negative to
172b0 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 leave the setti
172c0 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a ng unchanged..**
172d0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
172e0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 meter is a point
172f0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
17300 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 into which.** i
17310 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 s written 0 or 1
17320 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 to indicate whe
17330 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 ther triggers ar
17340 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e e disabled or en
17350 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 abled.** followi
17360 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 ng this call. T
17370 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
17380 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c ter may be a NUL
17390 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a L pointer, in.**
173a0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 which case the
173b0 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 trigger setting
173c0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 is not reported
173d0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a back. </dd>.**.*
173e0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
173f0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
17400 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
17410 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 1001 /* void
17420 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 * int int */.#de
17430 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
17440 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 NFIG_ENABLE_FKEY
17450 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 1002 /* in
17460 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e t int* */.#defin
17470 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
17480 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 G_ENABLE_TRIGGER
17490 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 1003 /* int i
174a0 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 nt* */.../*.** C
174b0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 API3REF: Enable
174c0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e Or Disable Exten
174d0 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 ded Result Codes
174e0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
174f0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 te3.**.** ^The s
17500 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
17510 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 result_codes() r
17520 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f outine enables o
17530 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a r disables the.*
17540 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 * [extended resu
17550 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 lt codes] featur
17560 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 e of SQLite. ^Th
17570 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c e extended resul
17580 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 t.** codes are d
17590 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
175a0 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 lt for historica
175b0 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e l compatibility.
175c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
175d0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
175e0 4c 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 L sqlite3_extend
175f0 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 ed_result_codes(
17600 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e sqlite3*, int on
17610 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 off);../*.** CAP
17620 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 I3REF: Last Inse
17630 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 rt Rowid.** METH
17640 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
17650 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e * ^Each entry in
17660 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 most SQLite tab
17670 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 les (except for
17680 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 [WITHOUT ROWID]
17690 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 tables).** has a
176a0 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 unique 64-bit s
176b0 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 igned.** integer
176c0 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 key called the
176d0 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 [ROWID | "rowid"
176e0 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 ]. ^The rowid is
176f0 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c always availabl
17700 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 e.** as an undec
17710 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d lared column nam
17720 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f ed ROWID, OID, o
17730 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e r _ROWID_ as lon
17740 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 g as those.** na
17750 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f mes are not also
17760 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 used by explici
17770 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c tly declared col
17780 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 umns. ^If.** the
17790 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c table has a col
177a0 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 umn of type [INT
177b0 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 EGER PRIMARY KEY
177c0 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 ] then that colu
177d0 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 mn.** is another
177e0 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 alias for the r
177f0 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 owid..**.** ^The
17800 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e sqlite3_last_in
17810 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e sert_rowid(D) in
17820 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
17830 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 the [rowid] of t
17840 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 he .** most rece
17850 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 nt successful [I
17860 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f NSERT] into a ro
17870 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 wid table or [vi
17880 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 rtual table].**
17890 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e on database conn
178a0 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e ection D..** ^In
178b0 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 serts into [WITH
178c0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 OUT ROWID] table
178d0 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 s are not record
178e0 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 ed..** ^If no su
178f0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
17900 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 ]s into rowid ta
17910 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 bles.** have eve
17920 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 r occurred on th
17930 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
17940 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 ction D, .** the
17950 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 n sqlite3_last_i
17960 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 nsert_rowid(D) r
17970 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a eturns zero..**.
17980 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 ** ^(If an [INSE
17990 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 RT] occurs withi
179a0 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 n a trigger or w
179b0 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c ithin a [virtual
179c0 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f table].** metho
179d0 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 d, then this rou
179e0 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e tine will return
179f0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 the [rowid] of
17a00 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 the inserted.**
17a10 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 row as long as t
17a20 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 he trigger or vi
17a30 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 rtual table meth
17a40 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a od is running..*
17a50 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 * But once the t
17a60 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 rigger or virtua
17a70 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 l table method e
17a80 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 nds, the value r
17a90 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 eturned .** by t
17aa0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 his routine reve
17ab0 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 rts to what it w
17ac0 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 as before the tr
17ad0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c igger or virtual
17ae0 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 .** table method
17af0 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 began.)^.**.**
17b00 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 ^An [INSERT] tha
17b10 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 t fails due to a
17b20 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
17b30 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a ation is not a.*
17b40 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e * successful [IN
17b50 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e SERT] and does n
17b60 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 ot change the va
17b70 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
17b80 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e this.** routine.
17b90 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f ^Thus INSERT O
17ba0 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f R FAIL, INSERT O
17bb0 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 R IGNORE, INSERT
17bc0 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a OR ROLLBACK,.**
17bd0 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 and INSERT OR A
17be0 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 BORT make no cha
17bf0 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 nges to the retu
17c00 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 rn value of this
17c10 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e .** routine when
17c20 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e their insertion
17c30 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 fails. ^(When
17c40 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 INSERT OR REPLAC
17c50 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 E.** encounters
17c60 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f a constraint vio
17c70 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 lation, it does
17c80 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a not fail. The.*
17c90 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 * INSERT continu
17ca0 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e es to completion
17cb0 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 after deleting
17cc0 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 rows that caused
17cd0 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 .** the constrai
17ce0 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e nt problem so IN
17cf0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 SERT OR REPLACE
17d00 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e will always chan
17d10 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e ge.** the return
17d20 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 value of this i
17d30 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a nterface.)^.**.*
17d40 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f * ^For the purpo
17d50 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ses of this rout
17d60 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d ine, an [INSERT]
17d70 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 is considered t
17d80 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 o.** be successf
17d90 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 ul even if it is
17da0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f subsequently ro
17db0 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a lled back..**.**
17dc0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 This function i
17dd0 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 s accessible to
17de0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 SQL statements v
17df0 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f ia the.** [last_
17e00 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 insert_rowid() S
17e10 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
17e20 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
17e30 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d e thread perform
17e40 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d s a new [INSERT]
17e50 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 on the same.**
17e60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
17e70 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 ion while the [s
17e80 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
17e90 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 rt_rowid()].** f
17ea0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
17eb0 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e ng and thus chan
17ec0 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 ges the last ins
17ed0 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 ert [rowid],.**
17ee0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 then the value r
17ef0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
17f00 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
17f10 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 rowid()] is.** u
17f20 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 npredictable and
17f30 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c might not equal
17f40 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 either the old
17f50 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 or the new.** la
17f60 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 st insert [rowid
17f70 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
17f80 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 sqlite3_int64 S
17f90 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
17fa0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
17fb0 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a t_rowid(sqlite3*
17fc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
17fd0 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 EF: Count The Nu
17fe0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 mber Of Rows Mod
17ff0 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a ified.** METHOD:
18000 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
18010 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
18020 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
18030 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 of rows modifie
18040 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a d, inserted or.*
18050 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 * deleted by the
18060 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 most recently c
18070 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c ompleted INSERT,
18080 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 UPDATE or DELET
18090 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f E.** statement o
180a0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
180b0 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 onnection specif
180c0 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 ied by the only
180d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 parameter..** ^E
180e0 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 xecuting any oth
180f0 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 er type of SQL s
18100 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f tatement does no
18110 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c t modify the val
18120 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 ue.** returned b
18130 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e y this function.
18140 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 .**.** ^Only cha
18150 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 nges made direct
18160 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 ly by the INSERT
18170 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
18180 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 TE statement are
18190 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d .** considered -
181a0 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 auxiliary chang
181b0 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 es caused by [CR
181c0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 EATE TRIGGER | t
181d0 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 riggers], .** [f
181e0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f oreign key actio
181f0 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d ns] or [REPLACE]
18200 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f constraint reso
18210 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 lution are not c
18220 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 ounted..** .** C
18230 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 hanges to a view
18240 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 that are interc
18250 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e epted by .** [IN
18260 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 STEAD OF trigger
18270 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 | INSTEAD OF tr
18280 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 iggers] are not
18290 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 counted. ^The va
182a0 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 lue .** returned
182b0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e by sqlite3_chan
182c0 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c ges() immediatel
182d0 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 y after an INSER
182e0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a T, UPDATE or .**
182f0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
18300 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 t run on a view
18310 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 is always zero.
18320 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 Only changes mad
18330 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 e to real .** ta
18340 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 bles are counted
18350 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 ..**.** Things a
18360 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 re more complica
18370 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 ted if the sqlit
18380 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e e3_changes() fun
18390 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 ction is.** exec
183a0 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 uted while a tri
183b0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 gger program is
183c0 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 running. This ma
183d0 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a y happen if the.
183e0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 ** program uses
183f0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 the [changes() S
18400 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 QL function], or
18410 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 if some other c
18420 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
18430 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 ion invokes sqli
18440 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 te3_changes() di
18450 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 rectly. Essentia
18460 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e lly:.** .** <ul>
18470 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 .** <li> ^(Bef
18480 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 ore entering a t
18490 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 rigger program t
184a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
184b0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 d by.** s
184c0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
184d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 function is sav
184e0 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 ed. After the tr
184f0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a igger program .*
18500 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e * has fin
18510 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 ished, the origi
18520 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 nal value is res
18530 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 tored.)^.** .**
18540 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 <li> ^(Within
18550 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 a trigger progra
18560 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 m each INSERT, U
18570 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 PDATE and DELETE
18580 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 .** stat
18590 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 ement sets the v
185a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
185b0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
185c0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 () .** up
185d0 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 on completion as
185e0 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 normal. Of cour
185f0 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 se, this value w
18600 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 ill not include
18610 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 .** any c
18620 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 hanges performed
18630 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 by sub-triggers
18640 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 , as the sqlite3
18650 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 _changes() .**
18660 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c value will
18670 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 be saved and re
18680 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 stored after eac
18690 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 h sub-trigger ha
186a0 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c s run.)^.** </ul
186b0 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d >.** .** ^This m
186c0 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 eans that if the
186d0 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 changes() SQL f
186e0 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 unction (or simi
186f0 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 lar) is used.**
18700 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 by the first INS
18710 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 ERT, UPDATE or D
18720 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 ELETE statement
18730 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 within a trigger
18740 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 , it .** returns
18750 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 the value as se
18760 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 t when the calli
18770 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 ng statement beg
18780 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a an executing..**
18790 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20 ^If it is used
187a0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 by the second or
187b0 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 subsequent such
187c0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
187d0 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 n a trigger .**
187e0 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c program, the val
187f0 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c ue returned refl
18800 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 ects the number
18810 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 of rows modified
18820 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 by the .** prev
18830 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 ious INSERT, UPD
18840 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 ATE or DELETE st
18850 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 atement within t
18860 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e he same trigger.
18870 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
18880 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 the [sqlite3_tot
18890 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e al_changes()] in
188a0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 terface, the.**
188b0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 [count_changes p
188c0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 ragma], and the
188d0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 [changes() SQL f
188e0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
188f0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
18900 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
18910 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
18920 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
18930 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
18940 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
18950 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
18960 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
18970 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 ed.** is unpredi
18980 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
18990 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 eaningful..*/.SQ
189a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
189b0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
189c0 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 te3_changes(sqli
189d0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
189e0 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 PI3REF: Total Nu
189f0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 mber Of Rows Mod
18a00 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a ified.** METHOD:
18a10 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
18a20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
18a30 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 turns the total
18a40 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 number of rows i
18a50 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 nserted, modifie
18a60 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 d or.** deleted
18a70 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c by all [INSERT],
18a80 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 [UPDATE] or [DE
18a90 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 LETE] statements
18aa0 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 completed.** si
18ab0 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 nce the database
18ac0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 connection was
18ad0 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e opened, includin
18ae0 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 g those executed
18af0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 as.** part of t
18b00 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e rigger programs.
18b10 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 ^Executing any
18b20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 other type of SQ
18b30 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 L statement.** d
18b40 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 oes not affect t
18b50 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
18b60 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 d by sqlite3_tot
18b70 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a al_changes()..**
18b80 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 .** ^Changes ma
18b90 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 de as part of [f
18ba0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f oreign key actio
18bb0 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 ns] are included
18bc0 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 in the.** count
18bd0 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 , but those made
18be0 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c as part of REPL
18bf0 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 ACE constraint r
18c00 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a esolution are.**
18c10 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 not. ^Changes t
18c20 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 o a view that ar
18c30 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 e intercepted by
18c40 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 INSTEAD OF trig
18c50 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 gers .** are not
18c60 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a counted..** .**
18c70 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
18c80 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
18c90 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 ] interface, the
18ca0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 .** [count_chang
18cb0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 es pragma], and
18cc0 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 the [total_chang
18cd0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f es() SQL functio
18ce0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 n]..**.** If a s
18cf0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d eparate thread m
18d00 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 akes changes on
18d10 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
18d20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
18d30 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 while [sqlite3_t
18d40 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 otal_changes()]
18d50 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
18d60 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 the value.** ret
18d70 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 urned is unpredi
18d80 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
18d90 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 eaningful..*/.SQ
18da0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
18db0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
18dc0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
18dd0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a s(sqlite3*);../*
18de0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
18df0 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 terrupt A Long-R
18e00 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 unning Query.**
18e10 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
18e20 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
18e30 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 tion causes any
18e40 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 pending database
18e50 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 operation to ab
18e60 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 ort and.** retur
18e70 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 n at its earlies
18e80 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 t opportunity. T
18e90 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 his routine is t
18ea0 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c ypically.** call
18eb0 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 ed in response t
18ec0 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 o a user action
18ed0 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 such as pressing
18ee0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 "Cancel".** or
18ef0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 Ctrl-C where the
18f00 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f user wants a lo
18f10 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 ng query operati
18f20 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d on to halt.** im
18f30 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a mediately..**.**
18f40 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 ^It is safe to
18f50 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e call this routin
18f60 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 e from a thread
18f70 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 different from t
18f80 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 he.** thread tha
18f90 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 t is currently r
18fa0 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 unning the datab
18fb0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 ase operation.
18fc0 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 But it.** is not
18fd0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 safe to call th
18fe0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 is routine with
18ff0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
19000 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 ection] that.**
19010 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 is closed or mig
19020 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 ht close before
19030 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
19040 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a t() returns..**.
19050 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 ** ^If an SQL op
19060 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 eration is very
19070 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 nearly finished
19080 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e at the time when
19090 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 .** sqlite3_inte
190a0 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 rrupt() is calle
190b0 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 d, then it might
190c0 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 not have an opp
190d0 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 ortunity.** to b
190e0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e e interrupted an
190f0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 d might continue
19100 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a to completion..
19110 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 **.** ^An SQL op
19120 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 eration that is
19130 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c interrupted will
19140 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
19150 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e INTERRUPT]..** ^
19160 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 If the interrupt
19170 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e ed SQL operation
19180 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 is an INSERT, U
19190 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
191a0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 .** that is insi
191b0 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 de an explicit t
191c0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e ransaction, then
191d0 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e the entire tran
191e0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 saction.** will
191f0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 be rolled back a
19200 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a utomatically..**
19210 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
19220 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 _interrupt(D) ca
19230 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 ll is in effect
19240 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e until all curren
19250 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 tly running.** S
19260 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e QL statements on
19270 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
19280 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 ction] D complet
19290 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c e. ^Any new SQL
192a0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 statements.** t
192b0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 hat are started
192c0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 after the sqlite
192d0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
192e0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 ll and before th
192f0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 e .** running st
19300 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 atements reaches
19310 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 zero are interr
19320 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 upted as if they
19330 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e had been.** run
19340 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 ning prior to th
19350 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
19360 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 upt() call. ^Ne
19370 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 w SQL statements
19380 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 .** that are sta
19390 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 rted after the r
193a0 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 unning statement
193b0 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a count reaches z
193c0 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 ero are.** not e
193d0 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 ffected by the s
193e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
193f0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 ()..** ^A call t
19400 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 o sqlite3_interr
19410 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 upt(D) that occu
19420 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 rs when there ar
19430 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 e no running.**
19440 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 SQL statements i
19450 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 s a no-op and ha
19460 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 s no effect on S
19470 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
19480 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 that are starte
19490 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 d after the sqli
194a0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
194b0 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a call returns..**
194c0 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 .** If the datab
194d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 ase connection c
194e0 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c loses while [sql
194f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
19500 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 ].** is running
19510 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 then bad things
19520 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 will likely happ
19530 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 en..*/.SQLITE_AP
19540 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 I void SQLITE_ST
19550 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 69 6e DCALL sqlite3_in
19560 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a terrupt(sqlite3*
19570 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
19580 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 EF: Determine If
19590 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
195a0 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a t Is Complete.**
195b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
195c0 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 es are useful du
195d0 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e ring command-lin
195e0 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 e input to deter
195f0 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 mine if the.** c
19600 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 urrently entered
19610 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 text seems to f
19620 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 orm a complete S
19630 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a QL statement or.
19640 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c ** if additional
19650 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 input is needed
19660 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 before sending
19670 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a the text into.**
19680 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 SQLite for pars
19690 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 ing. ^These rou
196a0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 tines return 1 i
196b0 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 f the input stri
196c0 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f ng.** appears to
196d0 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 be a complete S
196e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e QL statement. ^
196f0 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a A statement is j
19700 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 udged to be.** c
19710 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e omplete if it en
19720 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f ds with a semico
19730 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 lon token and is
19740 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 not a prefix of
19750 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 a.** well-forme
19760 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 d CREATE TRIGGER
19770 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 statement. ^Se
19780 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 micolons that ar
19790 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 e embedded withi
197a0 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 n.** string lite
197b0 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 rals or quoted i
197c0 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 dentifier names
197d0 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 or comments are
197e0 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 not.** independe
197f0 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 nt tokens (they
19800 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 are part of the
19810 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 token in which t
19820 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 hey are.** embed
19830 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f ded) and thus do
19840 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 not count as a
19850 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e statement termin
19860 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 ator. ^Whitespa
19870 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e ce.** and commen
19880 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 ts that follow t
19890 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c he final semicol
198a0 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a on are ignored..
198b0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
198c0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 tines return 0 i
198d0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
198e0 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 is incomplete.
198f0 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ^If a.** memory
19900 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 allocation fails
19910 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f , then SQLITE_NO
19920 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e MEM is returned.
19930 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
19940 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 utines do not pa
19950 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 rse the SQL stat
19960 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 ements thus.** w
19970 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 ill not detect s
19980 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 yntactically inc
19990 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a orrect SQL..**.*
199a0 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 * ^(If SQLite ha
199b0 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 s not been initi
199c0 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 alized using [sq
199d0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
199e0 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f ()] prior .** to
199f0 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 invoking sqlite
19a00 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 3_complete16() t
19a10 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 hen sqlite3_init
19a20 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f ialize() is invo
19a30 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 ked.** automatic
19a40 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f ally by sqlite3_
19a50 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 complete16(). I
19a60 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a f that initializ
19a70 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 ation fails,.**
19a80 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 then the return
19a90 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 value from sqlit
19aa0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 e3_complete16()
19ab0 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f will be non-zero
19ac0 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f .** regardless o
19ad0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
19ae0 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 the input SQL i
19af0 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a s complete.)^.**
19b00 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f .** The input to
19b10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 [sqlite3_comple
19b20 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 te()] must be a
19b30 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
19b40 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e ** UTF-8 string.
19b50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 .**.** The input
19b60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d to [sqlite3_com
19b70 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 plete16()] must
19b80 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e be a zero-termin
19b90 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 ated.** UTF-16 s
19ba0 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 tring in native
19bb0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 byte order..*/.S
19bc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
19bd0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
19be0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f ite3_complete(co
19bf0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a nst char *sql);.
19c00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
19c10 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
19c20 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
19c30 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c (const void *sql
19c40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
19c50 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 EF: Register A C
19c60 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c allback To Handl
19c70 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 e SQLITE_BUSY Er
19c80 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 rors.** KEYWORDS
19c90 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 : {busy-handler
19ca0 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 callback} {busy
19cb0 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 handler}.** METH
19cc0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
19cd0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 * ^The sqlite3_b
19ce0 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c usy_handler(D,X,
19cf0 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 P) routine sets
19d00 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
19d10 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 ion X.** that mi
19d20 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 ght be invoked w
19d30 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 ith argument P w
19d40 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 henever.** an at
19d50 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f tempt is made to
19d60 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 access a databa
19d70 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 se table associa
19d80 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 ted with.** [dat
19d90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
19da0 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 ] D when another
19db0 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 thread.** or pr
19dc0 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 ocess has the ta
19dd0 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 ble locked..** T
19de0 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f he sqlite3_busy_
19df0 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 handler() interf
19e00 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 ace is used to i
19e10 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c mplement.** [sql
19e20 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
19e30 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 t()] and [PRAGMA
19e40 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a busy_timeout]..
19e50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 **.** ^If the bu
19e60 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e sy callback is N
19e70 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 ULL, then [SQLIT
19e80 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 E_BUSY].** is re
19e90 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 turned immediate
19ea0 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 ly upon encounte
19eb0 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 ring the lock.
19ec0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c ^If the busy cal
19ed0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 lback.** is not
19ee0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 NULL, then the c
19ef0 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 allback might be
19f00 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 invoked with tw
19f10 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a o arguments..**.
19f20 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
19f30 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 gument to the bu
19f40 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 sy handler is a
19f50 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 copy of the void
19f60 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a * pointer which.
19f70 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 ** is the third
19f80 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
19f90 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
19fa0 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 (). ^The second
19fb0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
19fc0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
19fd0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 callback is the
19fe0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 number of times
19ff0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 that the busy h
1a000 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 andler has.** be
1a010 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 en invoked previ
1a020 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 ously for the sa
1a030 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 me locking event
1a040 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 . ^If the.** bu
1a050 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 sy callback retu
1a060 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 rns 0, then no a
1a070 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 dditional attemp
1a080 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a ts are made to.*
1a090 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 * access the dat
1a0a0 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 abase and [SQLIT
1a0b0 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 E_BUSY] is retur
1a0c0 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 ned.** to the ap
1a0d0 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 plication..** ^I
1a0e0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 f the callback r
1a0f0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
1a100 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 then another at
1a110 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 tempt.** is made
1a120 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 to access the d
1a130 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 atabase and the
1a140 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a cycle repeats..*
1a150 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 *.** The presenc
1a160 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 e of a busy hand
1a170 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 ler does not gua
1a180 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 rantee that it w
1a190 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a ill be invoked.*
1a1a0 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 * when there is
1a1b0 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e lock contention.
1a1c0 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 ^If SQLite dete
1a1d0 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f rmines that invo
1a1e0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a king the busy.**
1a1f0 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 handler could r
1a200 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c esult in a deadl
1a210 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 ock, it will go
1a220 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e ahead and return
1a230 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a [SQLITE_BUSY].*
1a240 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 * to the applica
1a250 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 tion instead of
1a260 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a invoking the .**
1a270 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
1a280 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 * Consider a sce
1a290 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 nario where one
1a2a0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 process is holdi
1a2b0 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 ng a read lock t
1a2c0 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 hat.** it is try
1a2d0 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 ing to promote t
1a2e0 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 o a reserved loc
1a2f0 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e k and.** a secon
1a300 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c d process is hol
1a310 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 ding a reserved
1a320 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 lock that it is
1a330 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f trying.** to pro
1a340 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 mote to an exclu
1a350 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 sive lock. The
1a360 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 first process ca
1a370 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 nnot proceed.**
1a380 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c because it is bl
1a390 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 ocked by the sec
1a3a0 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f ond and the seco
1a3b0 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f nd process canno
1a3c0 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 t.** proceed bec
1a3d0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
1a3e0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e ed by the first.
1a3f0 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 If both proces
1a400 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 ses.** invoke th
1a410 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c e busy handlers,
1a420 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 neither will ma
1a430 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e ke any progress.
1a440 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 Therefore,.**
1a450 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b SQLite returns [
1a460 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 SQLITE_BUSY] for
1a470 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
1a480 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 ss, hoping that
1a490 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 this.** will ind
1a4a0 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 uce the first pr
1a4b0 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 ocess to release
1a4c0 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 its read lock a
1a4d0 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 nd allow.** the
1a4e0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 second process t
1a4f0 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a o proceed..**.**
1a500 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 ^The default bu
1a510 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e sy callback is N
1a520 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ULL..**.** ^(The
1a530 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 re can only be a
1a540 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e single busy han
1a550 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 dler defined for
1a560 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 each.** [databa
1a570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
1a580 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 Setting a new b
1a590 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 usy handler clea
1a5a0 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f rs any.** previo
1a5b0 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 usly set handler
1a5c0 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 .)^ ^Note that
1a5d0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
1a5e0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d _busy_timeout()]
1a5f0 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e .** or evaluatin
1a600 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 g [PRAGMA busy_t
1a610 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 imeout=N] will c
1a620 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 hange the.** bus
1a630 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 y handler and th
1a640 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 us clear any pre
1a650 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 viously set busy
1a660 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 handler..**.**
1a670 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 The busy callbac
1a680 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b k should not tak
1a690 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 e any actions wh
1a6a0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a ich modify the.*
1a6b0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
1a6c0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b ction that invok
1a6d0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ed the busy hand
1a6e0 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 ler. In other w
1a6f0 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 ords,.** the bus
1a700 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 y handler is not
1a710 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 reentrant. Any
1a720 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a such actions.**
1a730 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 result in undef
1a740 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a ined behavior..*
1a750 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e * .** A busy han
1a760 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c dler must not cl
1a770 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ose the database
1a780 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f connection.** o
1a790 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 r [prepared stat
1a7a0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f ement] that invo
1a7b0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e ked the busy han
1a7c0 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f dler..*/.SQLITE_
1a7d0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
1a7e0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 TDCALL sqlite3_b
1a7f0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 usy_handler(sqli
1a800 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 te3*, int(*)(voi
1a810 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b d*,int), void*);
1a820 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1a830 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d : Set A Busy Tim
1a840 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 eout.** METHOD:
1a850 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
1a860 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 his routine sets
1a870 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 a [sqlite3_busy
1a880 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 _handler | busy
1a890 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c handler] that sl
1a8a0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 eeps.** for a sp
1a8b0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f ecified amount o
1a8c0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 f time when a ta
1a8d0 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 ble is locked.
1a8e0 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 ^The handler.**
1a8f0 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 will sleep multi
1a900 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 ple times until
1a910 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 at least "ms" mi
1a920 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c lliseconds of sl
1a930 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 eeping.** have a
1a940 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 ccumulated. ^Af
1a950 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 ter at least "ms
1a960 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f " milliseconds o
1a970 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 f sleeping,.** t
1a980 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 he handler retur
1a990 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 ns 0 which cause
1a9a0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 s [sqlite3_step(
1a9b0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 )] to return.**
1a9c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a [SQLITE_BUSY]..*
1a9d0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 *.** ^Calling th
1a9e0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 is routine with
1a9f0 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 an argument less
1aa00 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 than or equal t
1aa10 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 o zero.** turns
1aa20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e off all busy han
1aa30 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 dlers..**.** ^(T
1aa40 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 here can only be
1aa50 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 a single busy h
1aa60 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 andler for a par
1aa70 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 ticular.** [data
1aa80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1aa90 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f at any given mo
1aaa0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 ment. If anothe
1aab0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a r busy handler.*
1aac0 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 * was defined (
1aad0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 using [sqlite3_b
1aae0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 usy_handler()])
1aaf0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
1ab00 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
1ab10 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 , that other bus
1ab20 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 y handler is cle
1ab30 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 ared.)^.**.** Se
1ab40 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 e also: [PRAGMA
1ab50 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a busy_timeout].*
1ab60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
1ab70 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
1ab80 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
1ab90 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 eout(sqlite3*, i
1aba0 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 nt ms);../*.** C
1abb0 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 API3REF: Conveni
1abc0 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f ence Routines Fo
1abd0 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 r Running Querie
1abe0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
1abf0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ite3.**.** This
1ac00 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 is a legacy inte
1ac10 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 rface that is pr
1ac20 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b eserved for back
1ac30 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
1ac40 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 ity..** Use of t
1ac50 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
1ac60 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 not recommended
1ac70 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 ..**.** Definiti
1ac80 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 on: A <b>result
1ac90 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d table</b> is mem
1aca0 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 ory data structu
1acb0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 re created by th
1acc0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 e.** [sqlite3_ge
1acd0 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 t_table()] inter
1ace0 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 face. A result
1acf0 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 table records th
1ad00 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 e.** complete qu
1ad10 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d ery results from
1ad20 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 one or more que
1ad30 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ries..**.** The
1ad40 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c table conceptual
1ad50 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 ly has a number
1ad60 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 of rows and colu
1ad70 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 mns. But.** the
1ad80 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e se numbers are n
1ad90 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 ot part of the r
1ada0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 esult table itse
1adb0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 lf. These.** nu
1adc0 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e mbers are obtain
1add0 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 ed separately.
1ade0 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d Let N be the num
1adf0 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 ber of rows.** a
1ae00 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 nd M be the numb
1ae10 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a er of columns..*
1ae20 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
1ae30 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 ble is an array
1ae40 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a of pointers to z
1ae50 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
1ae60 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a TF-8 strings..**
1ae70 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 There are (N+1)
1ae80 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 *M elements in t
1ae90 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 he array. The f
1aea0 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 irst M pointers
1aeb0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f point.** to zero
1aec0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
1aed0 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 ngs that contai
1aee0 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 n the names of t
1aef0 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 he columns..** T
1af00 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 he remaining ent
1af10 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 ries all point t
1af20 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e o query results.
1af30 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 NULL values re
1af40 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 sult.** in NULL
1af50 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f pointers. All o
1af60 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 ther values are
1af70 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a in their UTF-8 z
1af80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
1af90 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 * string represe
1afa0 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 ntation as retur
1afb0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
1afc0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a column_text()]..
1afd0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 **.** A result t
1afe0 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 able might consi
1aff0 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 st of one or mor
1b000 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
1b010 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e ions..** It is n
1b020 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 ot safe to pass
1b030 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 a result table d
1b040 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 irectly to [sqli
1b050 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 te3_free()]..**
1b060 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 A result table s
1b070 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 hould be dealloc
1b080 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ated using [sqli
1b090 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
1b0a0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e ]..**.** ^(As an
1b0b0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 example of the
1b0c0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 result table for
1b0d0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 mat, suppose a q
1b0e0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 uery result.** i
1b0f0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
1b100 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1b110 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <pre>.**
1b120 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 Name | Ag
1b130 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d e.** ----
1b140 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1b150 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c ---.** Al
1b160 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a ice | 43.*
1b170 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 * Bob
1b180 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 | 28.**
1b190 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 Cindy
1b1a0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f | 21.** </pre></
1b1b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
1b1c0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 * There are two
1b1d0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e column (M==2) an
1b1e0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d d three rows (N=
1b1f0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a =3). Thus the.*
1b200 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 * result table h
1b210 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 as 8 entries. S
1b220 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c uppose the resul
1b230 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 t table is store
1b240 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 d.** in an array
1b250 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e names azResult.
1b260 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 Then azResult
1b270 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 holds this conte
1b280 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b nt:.**.** <block
1b290 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1b2a0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1b2b0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 91;0] = "Name";.
1b2c0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1b2d0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 lt[1] = "Age
1b2e0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1b2f0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 esult[2] = "
1b300 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 Alice";.**
1b310 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 azResult[3
1b320 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 ] = "43";.**
1b330 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1b340 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 ;4] = "Bob";.**
1b350 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1b360 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a #91;5] = "28";.*
1b370 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1b380 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 t[6] = "Cind
1b390 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a y";.** az
1b3a0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 Result[7] =
1b3b0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c "21";.** </pre><
1b3c0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a /blockquote>)^.*
1b3d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1b3e0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 3_get_table() fu
1b3f0 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 nction evaluates
1b400 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
1b410 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 semicolon-separa
1b420 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ted SQL statemen
1b430 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 ts in the zero-t
1b440 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a erminated UTF-8.
1b450 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 ** string of its
1b460 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
1b470 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 nd returns a res
1b480 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 ult table to the
1b490 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 .** pointer give
1b4a0 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 n in its 3rd par
1b4b0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 ameter..**.** Af
1b4c0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 ter the applicat
1b4d0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 ion has finished
1b4e0 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 with the result
1b4f0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 from sqlite3_ge
1b500 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 t_table(),.** it
1b510 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 must pass the r
1b520 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e esult table poin
1b530 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 ter to sqlite3_f
1b540 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f ree_table() in o
1b550 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 rder to.** relea
1b560 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 se the memory th
1b570 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e at was malloced.
1b580 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 Because of the
1b590 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c way the.** [sql
1b5a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 ite3_malloc()] h
1b5b0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 appens within sq
1b5c0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1b5d0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a ), the calling.*
1b5e0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
1b5f0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 not try to call
1b600 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1b610 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 directly. Only
1b620 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
1b630 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 e_table()] is ab
1b640 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 le to release th
1b650 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c e memory properl
1b660 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a y and safely..**
1b670 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
1b680 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 get_table() inte
1b690 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 rface is impleme
1b6a0 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 nted as a wrappe
1b6b0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c r around.** [sql
1b6c0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 ite3_exec()]. T
1b6d0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
1b6e0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 able() routine d
1b6f0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 oes not have acc
1b700 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e ess.** to any in
1b710 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 ternal data stru
1b720 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 ctures of SQLite
1b730 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 . It uses only
1b740 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e the public.** in
1b750 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 terface defined
1b760 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 here. As a cons
1b770 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 equence, errors
1b780 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 that occur in th
1b790 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 e.** wrapper lay
1b7a0 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 er outside of th
1b7b0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 e internal [sqli
1b7c0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c te3_exec()] call
1b7d0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c are not.** refl
1b7e0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 ected in subsequ
1b7f0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
1b800 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
1b810 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
1b820 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 errmsg()]..*/.SQ
1b830 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
1b840 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
1b850 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 te3_get_table(.
1b860 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
1b870 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 /* An ope
1b880 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 n database */.
1b890 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c const char *zSql
1b8a0 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 , /* SQL to
1b8b0 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a be evaluated */.
1b8c0 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 char ***pazRes
1b8d0 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c ult, /* Resul
1b8e0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 ts of the query
1b8f0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c */. int *pnRow,
1b900 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
1b910 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 mber of result r
1b920 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 ows written here
1b930 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c */. int *pnCol
1b940 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e umn, /* N
1b950 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
1b960 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 columns written
1b970 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a here */. char *
1b980 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 *pzErrmsg
1b990 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
1b9a0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
1b9b0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
1b9c0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
1b9d0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
1b9e0 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 e(char **result)
1b9f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1ba00 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 F: Formatted Str
1ba10 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e ing Printing Fun
1ba20 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ctions.**.** The
1ba30 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
1ba40 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 work-alikes of t
1ba50 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 he "printf()" fa
1ba60 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e mily of function
1ba70 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 s.** from the st
1ba80 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
1ba90 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 ..** These routi
1baa0 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d nes understand m
1bab0 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f ost of the commo
1bac0 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 n K&R formatting
1bad0 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 options,.** plu
1bae0 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 s some additiona
1baf0 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 l non-standard f
1bb00 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64 ormats, detailed
1bb10 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 below..** Note
1bb20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 that some of the
1bb30 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f more obscure fo
1bb40 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 rmatting options
1bb50 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 from recent.**
1bb60 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61 C-library standa
1bb70 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20 rds are omitted
1bb80 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d from this implem
1bb90 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 entation..**.**
1bba0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 ^The sqlite3_mpr
1bbb0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 intf() and sqlit
1bbc0 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f e3_vmprintf() ro
1bbd0 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 utines write the
1bbe0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e ir.** results in
1bbf0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
1bc00 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
1bc10 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 _malloc()]..** T
1bc20 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 he strings retur
1bc30 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f ned by these two
1bc40 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 routines should
1bc50 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 be.** released
1bc60 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 by [sqlite3_free
1bc70 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 ()]. ^Both rout
1bc80 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a ines return a.**
1bc90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 NULL pointer if
1bca0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1bcb0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ()] is unable to
1bcc0 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 allocate enough
1bcd0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f .** memory to ho
1bce0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 ld the resulting
1bcf0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e string..**.** ^
1bd00 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 (The sqlite3_snp
1bd10 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 rintf() routine
1bd20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 is similar to "s
1bd30 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a nprintf()" from.
1bd40 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 ** the standard
1bd50 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 C library. The
1bd60 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 result is writte
1bd70 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 n into the.** bu
1bd80 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 ffer supplied as
1bd90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
1bda0 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 meter whose size
1bdb0 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 is given by.**
1bdc0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
1bdd0 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 ter. Note that t
1bde0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a he order of the.
1bdf0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 ** first two par
1be00 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 ameters is rever
1be10 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 sed from snprint
1be20 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 f().)^ This is
1be30 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c an.** historical
1be40 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 accident that c
1be50 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 annot be fixed w
1be60 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a ithout breaking.
1be70 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d ** backwards com
1be80 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e patibility. ^(N
1be90 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 ote also that sq
1bea0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
1beb0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f .** returns a po
1bec0 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 inter to its buf
1bed0 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 fer instead of t
1bee0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
1bef0 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 characters actua
1bf00 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f lly written into
1bf10 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 the buffer.)^
1bf20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a We admit that.**
1bf30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
1bf40 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 haracters writte
1bf50 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 n would be a mor
1bf60 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a e useful return.
1bf70 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 ** value but we
1bf80 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 cannot change th
1bf90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
1bfa0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 of sqlite3_snpr
1bfb0 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 intf().** now wi
1bfc0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 thout breaking c
1bfd0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a ompatibility..**
1bfe0 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 .** ^As long as
1bff0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 the buffer size
1c000 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 is greater than
1c010 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e zero, sqlite3_sn
1c020 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 printf().** guar
1c030 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 antees that the
1c040 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 buffer is always
1c050 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1c060 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a . ^The first.**
1c070 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 parameter "n" i
1c080 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 s the total size
1c090 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 of the buffer,
1c0a0 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 including space
1c0b0 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 for.** the zero
1c0c0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 terminator. So
1c0d0 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 the longest stri
1c0e0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 ng that can be c
1c0f0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 ompletely.** wri
1c100 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 tten will be n-1
1c110 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a characters..**.
1c120 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1c130 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 vsnprintf() rout
1c140 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 ine is a varargs
1c150 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 version of sqli
1c160 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a te3_snprintf()..
1c170 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
1c180 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 ines all impleme
1c190 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e nt some addition
1c1a0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a al formatting.**
1c1b0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 options that ar
1c1c0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e e useful for con
1c1d0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 structing SQL st
1c1e0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c atements..** All
1c1f0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 of the usual pr
1c200 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e intf() formattin
1c210 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e g options apply.
1c220 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 In addition, t
1c230 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 here.** is are "
1c240 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20 %q", "%Q", "%w"
1c250 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 and "%z" options
1c260 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 ..**.** ^(The %q
1c270 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 option works li
1c280 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 ke %s in that it
1c290 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e substitutes a n
1c2a0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ul-terminated.**
1c2b0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 string from the
1c2c0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 argument list.
1c2d0 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 But %q also dou
1c2e0 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 bles every '\''
1c2f0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 character..** %q
1c300 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 is designed for
1c310 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 use inside a st
1c320 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 ring literal.)^
1c330 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 By doubling eac
1c340 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 h '\''.** charac
1c350 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 ter it escapes t
1c360 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e hat character an
1c370 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 d allows it to b
1c380 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a e inserted into.
1c390 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a ** the string..*
1c3a0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 *.** For example
1c3b0 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 , assume the str
1c3c0 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 ing variable zTe
1c3d0 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 xt contains text
1c3e0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
1c3f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1c400 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
1c410 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 Text = "It's a h
1c420 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c appy day!";.** <
1c430 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1c440 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e e>.**.** One can
1c450 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 use this text i
1c460 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
1c470 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a nt as follows:.*
1c480 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1c490 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
1c4a0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
1c4b0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
1c4c0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
1c4d0 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 S('%q')", zText)
1c4e0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 ;.** sqlite3_ex
1c4f0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 ec(db, zSQL, 0,
1c500 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 0, 0);.** sqlit
1c510 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a e3_free(zSQL);.*
1c520 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1c530 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 uote>.**.** Beca
1c540 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 use the %q forma
1c550 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 t string is used
1c560 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 , the '\'' chara
1c570 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a cter in zText.**
1c580 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 is escaped and
1c590 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 the SQL generate
1c5a0 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a d is as follows:
1c5b0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1c5c0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 te><pre>.** INS
1c5d0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 ERT INTO table1
1c5e0 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 VALUES('It''s a
1c5f0 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 happy day!').**
1c600 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
1c610 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 te>.**.** This i
1c620 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 s correct. Had
1c630 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 we used %s inste
1c640 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 ad of %q, the ge
1c650 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 nerated SQL.** w
1c660 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 ould have looked
1c670 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
1c680 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1c690 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
1c6a0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
1c6b0 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 S('It's a happy
1c6c0 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 day!');.** </pre
1c6d0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1c6e0 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 *.** This second
1c6f0 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 example is an S
1c700 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e QL syntax error.
1c710 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 As a general r
1c720 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a ule you should.*
1c730 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 * always use %q
1c740 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 instead of %s wh
1c750 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 en inserting tex
1c760 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 t into a string
1c770 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e literal..**.** ^
1c780 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 (The %Q option w
1c790 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 orks like %q exc
1c7a0 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 ept it also adds
1c7b0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 single quotes a
1c7c0 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 round.** the out
1c7d0 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 side of the tota
1c7e0 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 l string. Addit
1c7f0 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 ionally, if the
1c800 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 parameter in the
1c810 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 .** argument lis
1c820 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t is a NULL poin
1c830 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 ter, %Q substitu
1c840 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 tes the text "NU
1c850 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 LL" (without.**
1c860 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 single quotes).)
1c870 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 ^ So, for examp
1c880 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 le, one could sa
1c890 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 y:.**.** <blockq
1c8a0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
1c8b0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
1c8c0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
1c8d0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
1c8e0 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 ALUES(%Q)", zTex
1c8f0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f t);.** sqlite3_
1c900 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 exec(db, zSQL, 0
1c910 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c , 0, 0);.** sql
1c920 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b ite3_free(zSQL);
1c930 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1c940 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
1c950 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c e code above wil
1c960 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 l render a corre
1c970 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ct SQL statement
1c980 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 in the zSQL.**
1c990 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 variable even if
1c9a0 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 the zText varia
1c9b0 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ble is a NULL po
1c9c0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 inter..**.** ^(T
1c9d0 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 he "%w" formatti
1c9e0 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b ng option is lik
1c9f0 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68 e "%q" except th
1ca00 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f at it expects to
1ca10 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 .** be contained
1ca20 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 within double-q
1ca30 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66 uotes instead of
1ca40 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 single quotes,
1ca50 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 and it.** escape
1ca60 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f s the double-quo
1ca70 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73 te character ins
1ca80 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67 tead of the sing
1ca90 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 le-quote.** char
1caa0 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25 acter.)^ The "%
1cab0 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 w" formatting op
1cac0 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 tion is intended
1cad0 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65 for safely inse
1cae0 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 rting.** table a
1caf0 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 nd column names
1cb00 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 into a construct
1cb10 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ed SQL statement
1cb20 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 ..**.** ^(The "%
1cb30 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 z" formatting op
1cb40 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 tion works like
1cb50 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 "%s" but with th
1cb60 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 e.** addition th
1cb70 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 at after the str
1cb80 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 ing has been rea
1cb90 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 d and copied int
1cba0 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c o.** the result,
1cbb0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1cbc0 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 ] is called on t
1cbd0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e he input string.
1cbe0 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 )^.*/.SQLITE_API
1cbf0 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 43 44 char *SQLITE_CD
1cc00 45 43 4c 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 ECL sqlite3_mpri
1cc10 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c ntf(const char*,
1cc20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ...);.SQLITE_API
1cc30 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 char *SQLITE_ST
1cc40 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 6d DCALL sqlite3_vm
1cc50 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 printf(const cha
1cc60 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 r*, va_list);.SQ
1cc70 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 LITE_API char *S
1cc80 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 QLITE_CDECL sqli
1cc90 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 te3_snprintf(int
1cca0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 ,char*,const cha
1ccb0 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 r*, ...);.SQLITE
1ccc0 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 _API char *SQLIT
1ccd0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
1cce0 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 3_vsnprintf(int,
1ccf0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
1cd00 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a *, va_list);../*
1cd10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
1cd20 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 mory Allocation
1cd30 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 Subsystem.**.**
1cd40 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
1cd50 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 uses these three
1cd60 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c routines for al
1cd70 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 l of its own.**
1cd80 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 internal memory
1cd90 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
1cda0 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 . "Core" in the
1cdb0 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 previous sentenc
1cdc0 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e e.** does not in
1cdd0 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d clude operating-
1cde0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 system specific
1cdf0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
1ce00 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 on. The.** Wind
1ce10 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 ows VFS uses nat
1ce20 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 ive malloc() and
1ce30 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 free() for some
1ce40 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a operations..**.
1ce50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1ce60 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 malloc() routine
1ce70 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
1ce80 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a er to a block.**
1ce90 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 of memory at le
1cea0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c ast N bytes in l
1ceb0 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 ength, where N i
1cec0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e s the parameter.
1ced0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f .** ^If sqlite3_
1cee0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 malloc() is unab
1cef0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 le to obtain suf
1cf00 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 ficient free.**
1cf10 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 memory, it retur
1cf20 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
1cf30 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 r. ^If the para
1cf40 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 meter N to.** sq
1cf50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 lite3_malloc() i
1cf60 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 s zero or negati
1cf70 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ve then sqlite3_
1cf80 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 malloc() returns
1cf90 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 .** a NULL point
1cfa0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
1cfb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 qlite3_malloc64(
1cfc0 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 N) routine works
1cfd0 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 just like.** sq
1cfe0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 lite3_malloc(N)
1cff0 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 except that N is
1d000 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d an unsigned 64-
1d010 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 bit integer inst
1d020 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e ead.** of a sign
1d030 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 ed 32-bit intege
1d040 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e r..**.** ^Callin
1d050 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 g sqlite3_free()
1d060 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
1d070 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 previously retur
1d080 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 ned.** by sqlite
1d090 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 3_malloc() or sq
1d0a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
1d0b0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 releases that me
1d0c0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 mory so.** that
1d0d0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 it might be reus
1d0e0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 ed. ^The sqlite
1d0f0 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 3_free() routine
1d100 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 is.** a no-op i
1d110 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 f is called with
1d120 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1d130 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c Passing a NULL
1d140 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 pointer.** to s
1d150 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 qlite3_free() is
1d160 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 harmless. Afte
1d170 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d r being freed, m
1d180 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 emory.** should
1d190 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 neither be read
1d1a0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 nor written. Ev
1d1b0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 en reading previ
1d1c0 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d ously freed.** m
1d1d0 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 emory might resu
1d1e0 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 lt in a segmenta
1d1f0 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 tion fault or ot
1d200 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 her severe error
1d210 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 ..** Memory corr
1d220 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e uption, a segmen
1d230 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 tation fault, or
1d240 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
1d250 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 ror.** might res
1d260 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 ult if sqlite3_f
1d270 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 ree() is called
1d280 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 with a non-NULL
1d290 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 pointer that.**
1d2a0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 was not obtained
1d2b0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 from sqlite3_ma
1d2c0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 lloc() or sqlite
1d2d0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 3_realloc()..**.
1d2e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1d2f0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 realloc(X,N) int
1d300 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 erface attempts
1d310 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 to resize a.** p
1d320 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f rior memory allo
1d330 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 cation X to be a
1d340 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e t least N bytes.
1d350 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 .** ^If the X pa
1d360 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
1d370 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a e3_realloc(X,N).
1d380 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 ** is a NULL poi
1d390 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 nter then its be
1d3a0 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 havior is identi
1d3b0 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a cal to calling.*
1d3c0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
1d3d0 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 (N)..** ^If the
1d3e0 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 N parameter to s
1d3f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
1d400 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a ,N) is zero or.*
1d410 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 * negative then
1d420 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
1d430 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 exactly the same
1d440 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 as calling.** s
1d450 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a qlite3_free(X)..
1d460 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c ** ^sqlite3_real
1d470 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 loc(X,N) returns
1d480 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
1d490 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1d4a0 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 n.** of at least
1d4b0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 N bytes in size
1d4c0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 or NULL if insu
1d4d0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 fficient memory
1d4e0 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a is available..**
1d4f0 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 ^If M is the si
1d500 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 ze of the prior
1d510 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e allocation, then
1d520 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a min(N,M) bytes.
1d530 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 ** of the prior
1d540 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 allocation are c
1d550 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 opied into the b
1d560 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 eginning of buff
1d570 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 er returned.** b
1d580 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f y sqlite3_reallo
1d590 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 c(X,N) and the p
1d5a0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
1d5b0 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 is freed..** ^If
1d5c0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1d5d0 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 (X,N) returns NU
1d5e0 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 LL and N is posi
1d5f0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a tive, then the.*
1d600 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 * prior allocati
1d610 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e on is not freed.
1d620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1d630 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c te3_realloc64(X,
1d640 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f N) interfaces wo
1d650 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a rks the same as.
1d660 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c ** sqlite3_reall
1d670 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 oc(X,N) except t
1d680 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 hat N is a 64-bi
1d690 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 t unsigned integ
1d6a0 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 er instead.** of
1d6b0 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 a 32-bit signed
1d6c0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 integer..**.**
1d6d0 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 ^If X is a memor
1d6e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 y allocation pre
1d6f0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 viously obtained
1d700 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 from sqlite3_ma
1d710 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 lloc(),.** sqlit
1d720 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 e3_malloc64(), s
1d730 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1d740 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 , or sqlite3_rea
1d750 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a lloc64(), then.*
1d760 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 * sqlite3_msize(
1d770 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 X) returns the s
1d780 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f ize of that memo
1d790 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e ry allocation in
1d7a0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 bytes..** ^The
1d7b0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
1d7c0 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 y sqlite3_msize(
1d7d0 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 X) might be larg
1d7e0 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 er than the numb
1d7f0 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 er.** of bytes r
1d800 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 equested when X
1d810 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 was allocated.
1d820 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 ^If X is a NULL
1d830 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 pointer then.**
1d840 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 sqlite3_msize(X)
1d850 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 returns zero.
1d860 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 If X points to s
1d870 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 omething that is
1d880 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 not.** the begi
1d890 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 nning of memory
1d8a0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 allocation, or i
1d8b0 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 f it points to a
1d8c0 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c formerly.** val
1d8d0 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 id memory alloca
1d8e0 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f tion that has no
1d8f0 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 w been freed, th
1d900 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a en the behavior.
1d910 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 ** of sqlite3_ms
1d920 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 ize(X) is undefi
1d930 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 ned and possibly
1d940 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 harmful..**.**
1d950 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 ^The memory retu
1d960 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
1d970 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 malloc(), sqlite
1d980 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 3_realloc(),.**
1d990 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 sqlite3_malloc64
1d9a0 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f (), and sqlite3_
1d9b0 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 realloc64().** i
1d9c0 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 s always aligned
1d9d0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 to at least an
1d9e0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 8 byte boundary,
1d9f0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 or to a.** 4 by
1da00 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 te boundary if t
1da10 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 he [SQLITE_4_BYT
1da20 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 E_ALIGNED_MALLOC
1da30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a ] compile-time.*
1da40 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 * option is used
1da50 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 ..**.** In SQLit
1da60 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 e version 3.5.0
1da70 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 and 3.5.1, it wa
1da80 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 s possible to de
1da90 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 fine.** the SQLI
1daa0 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 TE_OMIT_MEMORY_A
1dab0 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 LLOCATION which
1dac0 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 would cause the
1dad0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c built-in.** impl
1dae0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
1daf0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ese routines to
1db00 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 be omitted. Tha
1db10 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 t capability.**
1db20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f is no longer pro
1db30 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 vided. Only bui
1db40 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
1db50 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 ocators can be u
1db60 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 sed..**.** Prior
1db70 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 to SQLite versi
1db80 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 on 3.7.10, the W
1db90 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 indows OS interf
1dba0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 ace layer called
1dbb0 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d .** the system m
1dbc0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
1dbd0 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e () directly when
1dbe0 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 converting.** f
1dbf0 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e ilenames between
1dc00 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 the UTF-8 encod
1dc10 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 ing used by SQLi
1dc20 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 te.** and whatev
1dc30 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f er filename enco
1dc40 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 ding is used by
1dc50 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 the particular W
1dc60 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c indows.** instal
1dc70 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 lation. Memory
1dc80 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
1dc90 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c s were detected,
1dca0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 but.** they wer
1dcb0 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 e reported back
1dcc0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f as [SQLITE_CANTO
1dcd0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 PEN] or.** [SQLI
1dce0 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 TE_IOERR] rather
1dcf0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f than [SQLITE_NO
1dd00 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 MEM]..**.** The
1dd10 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 pointer argument
1dd20 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 s to [sqlite3_fr
1dd30 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ee()] and [sqlit
1dd40 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a e3_realloc()].**
1dd50 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
1dd60 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 NULL or else poi
1dd70 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 nters obtained f
1dd80 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 rom a prior.** i
1dd90 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 nvocation of [sq
1dda0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
1ddb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c or [sqlite3_real
1ddc0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 loc()] that have
1ddd0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e .** not yet been
1dde0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a released..**.**
1ddf0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
1de00 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f must not read o
1de10 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 r write any part
1de20 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f of.** a block o
1de30 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 f memory after i
1de40 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 t has been relea
1de50 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 sed using.** [sq
1de60 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 lite3_free()] or
1de70 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
1de80 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f c()]..*/.SQLITE_
1de90 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 API void *SQLITE
1dea0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
1deb0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 _malloc(int);.SQ
1dec0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 LITE_API void *S
1ded0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
1dee0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 lite3_malloc64(s
1def0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a qlite3_uint64);.
1df00 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
1df10 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
1df20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1df30 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c void*, int);.SQL
1df40 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 ITE_API void *SQ
1df50 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1df60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 ite3_realloc64(v
1df70 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 oid*, sqlite3_ui
1df80 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 nt64);.SQLITE_AP
1df90 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 I void SQLITE_ST
1dfa0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 DCALL sqlite3_fr
1dfb0 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 ee(void*);.SQLIT
1dfc0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 75 69 E_API sqlite3_ui
1dfd0 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 nt64 SQLITE_STDC
1dfe0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a ALL sqlite3_msiz
1dff0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a e(void*);../*.**
1e000 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
1e010 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 y Allocator Stat
1e020 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c istics.**.** SQL
1e030 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 ite provides the
1e040 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 se two interface
1e050 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 s for reporting
1e060 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a on the status.**
1e070 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
1e080 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c _malloc()], [sql
1e090 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e ite3_free()], an
1e0a0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d [sqlite3_reall
1e0b0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 oc()].** routine
1e0c0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 s, which form th
1e0d0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 e built-in memor
1e0e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 y allocation sub
1e0f0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 system..**.** ^T
1e100 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f he [sqlite3_memo
1e110 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 ry_used()] routi
1e120 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ne returns the n
1e130 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a umber of bytes.*
1e140 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 * of memory curr
1e150 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e ently outstandin
1e160 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 g (malloced but
1e170 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e not freed)..** ^
1e180 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
1e190 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d ory_highwater()]
1e1a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
1e1b0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 the maximum.**
1e1c0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 value of [sqlite
1e1d0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
1e1e0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d since the high-
1e1f0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 water mark.** wa
1e200 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e s last reset. ^
1e210 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 The values retur
1e220 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
1e230 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 memory_used()] a
1e240 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d nd.** [sqlite3_m
1e250 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
1e260 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f )] include any o
1e270 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 verhead.** added
1e280 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 by SQLite in it
1e290 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
1e2a0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c of [sqlite3_mal
1e2b0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e loc()],.** but n
1e2c0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 ot overhead adde
1e2d0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 d by the any und
1e2e0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c erlying system l
1e2f0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e ibrary.** routin
1e300 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 es that [sqlite3
1e310 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 _malloc()] may c
1e320 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 all..**.** ^The
1e330 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 memory high-wate
1e340 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 r mark is reset
1e350 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 to the current v
1e360 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 alue of.** [sqli
1e370 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
1e380 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 )] if and only i
1e390 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
1e3a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d to.** [sqlite3_m
1e3b0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
1e3c0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 )] is true. ^Th
1e3d0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
1e3e0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f .** by [sqlite3_
1e3f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
1e400 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 (1)] is the high
1e410 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 -water mark.** p
1e420 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 rior to the rese
1e430 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 t..*/.SQLITE_API
1e440 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 sqlite3_int64 S
1e450 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
1e460 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
1e470 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f d(void);.SQLITE_
1e480 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
1e490 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 4 SQLITE_STDCALL
1e4a0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f sqlite3_memory_
1e4b0 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 highwater(int re
1e4c0 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a setFlag);../*.**
1e4d0 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 CAPI3REF: Pseud
1e4e0 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 o-Random Number
1e4f0 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 Generator.**.**
1e500 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 SQLite contains
1e510 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 a high-quality p
1e520 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d seudo-random num
1e530 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 ber generator (P
1e540 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 RNG) used to.**
1e550 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 select random [R
1e560 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 OWID | ROWIDs] w
1e570 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 hen inserting ne
1e580 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 w records into a
1e590 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 table that.** a
1e5a0 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 lready uses the
1e5b0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 largest possible
1e5c0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 [ROWID]. The P
1e5d0 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 RNG is also used
1e5e0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c for.** the buil
1e5f0 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e d-in random() an
1e600 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 d randomblob() S
1e610 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 QL functions. T
1e620 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c his interface al
1e630 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 lows.** applicat
1e640 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 ions to access t
1e650 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 he same PRNG for
1e660 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e other purposes.
1e670 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 .**.** ^A call t
1e680 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 o this routine s
1e690 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 tores N bytes of
1e6a0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f randomness into
1e6b0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 buffer P..** ^T
1e6c0 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 he P parameter c
1e6d0 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 an be a NULL poi
1e6e0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 nter..**.** ^If
1e6f0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 this routine has
1e700 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f not been previo
1e710 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 usly called or i
1e720 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a f the previous.*
1e730 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 * call had N les
1e740 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 s than one or a
1e750 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 NULL pointer for
1e760 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e P, then the PRN
1e770 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 G is.** seeded u
1e780 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 sing randomness
1e790 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 obtained from th
1e7a0 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 e xRandomness me
1e7b0 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 thod of.** the d
1e7c0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
1e7d0 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 vfs] object..**
1e7e0 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 ^If the previous
1e7f0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f call to this ro
1e800 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f utine had an N o
1e810 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 f 1 or more and
1e820 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 a.** non-NULL P
1e830 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d then the pseudo-
1e840 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 randomness is ge
1e850 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 nerated.** inter
1e860 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 nally and withou
1e870 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 t recourse to th
1e880 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 e [sqlite3_vfs]
1e890 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d xRandomness.** m
1e8a0 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ethod..*/.SQLITE
1e8b0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 _API void SQLITE
1e8c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
1e8d0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 _randomness(int
1e8e0 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a N, void *P);../*
1e8f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
1e900 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f mpile-Time Autho
1e910 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 rization Callbac
1e920 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ks.** METHOD: sq
1e930 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 lite3.**.** ^Thi
1e940 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 s routine regist
1e950 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 ers an authorize
1e960 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 r callback with
1e970 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 a particular.**
1e980 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1e990 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 tion], supplied
1e9a0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
1e9b0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 ument..** ^The a
1e9c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1e9d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 ck is invoked as
1e9e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
1e9f0 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c are being compil
1ea00 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 ed.** by [sqlite
1ea10 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
1ea20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 its variants [sq
1ea30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1ea40 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
1ea50 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e _prepare16()] an
1ea60 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
1ea70 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 re16_v2()]. ^At
1ea80 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e various.** poin
1ea90 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f ts during the co
1eaa0 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 mpilation proces
1eab0 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 s, as logic is b
1eac0 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 eing created.**
1ead0 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
1eae0 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 us actions, the
1eaf0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1eb00 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 ack is invoked t
1eb10 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 o.** see if thos
1eb20 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c e actions are al
1eb30 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 lowed. ^The aut
1eb40 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1eb50 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 should.** retur
1eb60 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f n [SQLITE_OK] to
1eb70 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f allow the actio
1eb80 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 n, [SQLITE_IGNOR
1eb90 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 E] to disallow t
1eba0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 he.** specific a
1ebb0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 ction but allow
1ebc0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
1ebd0 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f t to continue to
1ebe0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c be.** compiled,
1ebf0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 or [SQLITE_DENY
1ec00 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 ] to cause the e
1ec10 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d ntire SQL statem
1ec20 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a ent to be.** rej
1ec30 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 ected with an er
1ec40 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 ror. ^If the au
1ec50 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1ec60 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 k returns.** any
1ec70 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 value other tha
1ec80 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 n [SQLITE_IGNORE
1ec90 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ], [SQLITE_OK],
1eca0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d or [SQLITE_DENY]
1ecb0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 .** then the [sq
1ecc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1ecd0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e ()] or equivalen
1ece0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 t call that trig
1ecf0 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 gered.** the aut
1ed00 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 horizer will fai
1ed10 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 l with an error
1ed20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 message..**.** W
1ed30 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
1ed40 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
1ed50 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 _OK], that means
1ed60 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a the operation.*
1ed70 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f * requested is o
1ed80 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 k. ^When the ca
1ed90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
1eda0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 SQLITE_DENY], th
1edb0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 e.** [sqlite3_pr
1edc0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 epare_v2()] or e
1edd0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 quivalent call t
1ede0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 hat triggered th
1edf0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 e.** authorizer
1ee00 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 will fail with a
1ee10 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 n error message
1ee20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a explaining that.
1ee30 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e ** access is den
1ee40 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ied. .**.** ^The
1ee50 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
1ee60 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
1ee70 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 er callback is a
1ee80 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 copy of the thi
1ee90 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 rd.** parameter
1eea0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 to the sqlite3_s
1eeb0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 et_authorizer()
1eec0 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 interface. ^The
1eed0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1eee0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 .** to the callb
1eef0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ack is an intege
1ef00 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c r [SQLITE_COPY |
1ef10 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 action code] th
1ef20 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 at specifies.**
1ef30 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 the particular a
1ef40 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
1ef50 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 orized. ^The thi
1ef60 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 rd through sixth
1ef70 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 parameters.** t
1ef80 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 o the callback a
1ef90 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 re zero-terminat
1efa0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 ed strings that
1efb0 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e contain addition
1efc0 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 al.** details ab
1efd0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 out the action t
1efe0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e o be authorized.
1eff0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 .**.** ^If the a
1f000 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 ction code is [S
1f010 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 QLITE_READ].** a
1f020 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 nd the callback
1f030 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
1f040 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 IGNORE] then the
1f050 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
1f060 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 atement] stateme
1f070 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 nt is constructe
1f080 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a d to substitute.
1f090 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 ** a NULL value
1f0a0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 in place of the
1f0b0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 table column tha
1f0c0 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 t would have.**
1f0d0 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 been read if [SQ
1f0e0 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 LITE_OK] had bee
1f0f0 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 n returned. The
1f100 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
1f110 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 .** return can b
1f120 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 e used to deny a
1f130 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 n untrusted user
1f140 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 access to indiv
1f150 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 idual.** columns
1f160 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 of a table..**
1f170 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 ^If the action c
1f180 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 ode is [SQLITE_D
1f190 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 ELETE] and the c
1f1a0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a allback returns.
1f1b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 ** [SQLITE_IGNOR
1f1c0 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c E] then the [DEL
1f1d0 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 ETE] operation p
1f1e0 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a roceeds but the.
1f1f0 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 ** [truncate opt
1f200 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 imization] is di
1f210 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 sabled and all r
1f220 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 ows are deleted
1f230 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a individually..**
1f240 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 .** An authorize
1f250 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b r is used when [
1f260 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 sqlite3_prepare
1f270 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 | preparing].**
1f280 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 SQL statements f
1f290 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 rom an untrusted
1f2a0 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 source, to ensu
1f2b0 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 re that the SQL
1f2c0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f statements.** do
1f2d0 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 not try to acce
1f2e0 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 ss data they are
1f2f0 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 not allowed to
1f300 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 see, or that the
1f310 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 y do not.** try
1f320 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 to execute malic
1f330 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 ious statements
1f340 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 that damage the
1f350 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a database. For.*
1f360 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 * example, an ap
1f370 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c plication may al
1f380 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e low a user to en
1f390 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a ter arbitrary.**
1f3a0 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 SQL queries for
1f3b0 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 evaluation by a
1f3c0 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 database. But
1f3d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
1f3e0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 does.** not want
1f3f0 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 the user to be
1f400 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 able to make arb
1f410 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 itrary changes t
1f420 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 o the.** databas
1f430 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 e. An authorize
1f440 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 r could then be
1f450 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 put in place whi
1f460 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 le the.** user-e
1f470 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 ntered SQL is be
1f480 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
1f490 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d pare | prepared]
1f4a0 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f that.** disallo
1f4b0 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 ws everything ex
1f4c0 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 cept [SELECT] st
1f4d0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
1f4e0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
1f4f0 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 t need to proces
1f500 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 s SQL from untru
1f510 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 sted sources.**
1f520 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 might also consi
1f530 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 der lowering res
1f540 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 ource limits usi
1f550 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 ng [sqlite3_limi
1f560 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 t()].** and limi
1f570 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 ting database si
1f580 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 ze using the [ma
1f590 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 x_page_count] [P
1f5a0 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 RAGMA].** in add
1f5b0 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 ition to using a
1f5c0 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a n authorizer..**
1f5d0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e .** ^(Only a sin
1f5e0 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 gle authorizer c
1f5f0 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f an be in place o
1f600 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e n a database con
1f610 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 nection.** at a
1f620 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c time. Each call
1f630 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f to sqlite3_set_
1f640 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 authorizer overr
1f650 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 ides the.** prev
1f660 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 ious call.)^ ^D
1f670 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f isable the autho
1f680 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c rizer by install
1f690 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 ing a NULL callb
1f6a0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 ack..** The auth
1f6b0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c orizer is disabl
1f6c0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a ed by default..*
1f6d0 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 *.** The authori
1f6e0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 zer callback mus
1f6f0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
1f700 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
1f710 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
1f720 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
1f730 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 at invoked the a
1f740 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1f750 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 ck..** Note that
1f760 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1f770 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
1f780 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 ite3_step()] bot
1f790 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a h modify their.*
1f7a0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
1f7b0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
1f7c0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
1f7d0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
1f7e0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 raph..**.** ^Whe
1f7f0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
1f800 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 re_v2()] is used
1f810 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 to prepare a st
1f820 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 atement, the.**
1f830 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 statement might
1f840 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 be re-prepared d
1f850 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 uring [sqlite3_s
1f860 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 tep()] due to a
1f870 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 .** schema chang
1f880 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 e. Hence, the a
1f890 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
1f8a0 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 d ensure that th
1f8b0 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 e.** correct aut
1f8c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1f8d0 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 remains in plac
1f8e0 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 e during the [sq
1f8f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a lite3_step()]..*
1f900 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 *.** ^Note that
1f910 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
1f920 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
1f930 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a ed only during.*
1f940 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
1f950 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 re()] or its var
1f960 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a iants. Authoriz
1f970 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 ation is not.**
1f980 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 performed during
1f990 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 statement evalu
1f9a0 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 ation in [sqlite
1f9b0 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 3_step()], unles
1f9c0 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 s.** as stated i
1f9d0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 n the previous p
1f9e0 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 aragraph, sqlite
1f9f0 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 3_step() invokes
1fa00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 .** sqlite3_prep
1fa10 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 are_v2() to repr
1fa20 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e epare a statemen
1fa30 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 t after a schema
1fa40 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 change..*/.SQLI
1fa50 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
1fa60 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
1fa70 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
1fa80 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 (. sqlite3*,.
1fa90 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 int (*xAuth)(voi
1faa0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
1fab0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
1fac0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
1fad0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 char*),. void
1fae0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f *pUserData.);../
1faf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
1fb00 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e uthorizer Return
1fb10 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Codes.**.** The
1fb20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
1fb30 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
1fb40 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 rizer callback f
1fb50 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a unction] must.**
1fb60 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b return either [
1fb70 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e SQLITE_OK] or on
1fb80 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 e of these two c
1fb90 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 onstants in orde
1fba0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 r.** to signal S
1fbb0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 QLite whether or
1fbc0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 not the action
1fbd0 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 is permitted. S
1fbe0 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ee the.** [sqlit
1fbf0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1fc00 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 r | authorizer d
1fc10 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
1fc20 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
1fc30 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
1fc40 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c ** Note that SQL
1fc50 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c ITE_IGNORE is al
1fc60 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f so used as a [co
1fc70 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f nflict resolutio
1fc80 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 n mode].** retur
1fc90 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 ned from the [sq
1fca0 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f lite3_vtab_on_co
1fcb0 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 nflict()] interf
1fcc0 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ace..*/.#define
1fcd0 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 SQLITE_DENY 1
1fce0 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 /* Abort the S
1fcf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 QL statement wit
1fd00 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 h an error */.#d
1fd10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e efine SQLITE_IGN
1fd20 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 ORE 2 /* Don't
1fd30 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 allow access, b
1fd40 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 ut don't generat
1fd50 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f e an error */../
1fd60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
1fd70 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e uthorizer Action
1fd80 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Codes.**.** The
1fd90 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
1fda0 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 thorizer()] inte
1fdb0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
1fdc0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
1fdd0 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 ion.** that is i
1fde0 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 nvoked to author
1fdf0 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 ize certain SQL
1fe00 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e statement action
1fe10 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e s. The.** secon
1fe20 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
1fe30 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
1fe40 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 n integer code t
1fe50 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a hat specifies.**
1fe60 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 what action is
1fe70 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 being authorized
1fe80 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 . These are the
1fe90 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 integer action
1fea0 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 codes that.** th
1feb0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1fec0 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 lback may be pas
1fed0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 sed..**.** These
1fee0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c action code val
1fef0 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 ues signify what
1ff00 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 kind of operati
1ff10 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 on is to be.** a
1ff20 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 uthorized. The
1ff30 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 3rd and 4th para
1ff40 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 meters to the au
1ff50 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 thorization.** c
1ff60 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1ff70 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 will be paramet
1ff80 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 ers or NULL depe
1ff90 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f nding on which o
1ffa0 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 f these.** codes
1ffb0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 is used as the
1ffc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1ffd0 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 . ^(The 5th par
1ffe0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ameter to the.**
1fff0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
20000 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 back is the name
20010 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
20020 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 ("main", "temp"
20030 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 ,.** etc.) if ap
20040 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 plicable.)^ ^Th
20050 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 6th parameter
20060 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 to the authorize
20070 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 r callback.** is
20080 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
20090 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 inner-most trig
200a0 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 ger or view that
200b0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
200c0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 for.** the acces
200d0 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c s attempt or NUL
200e0 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 L if this access
200f0 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 attempt is dire
20100 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 ctly from.** top
20110 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e -level SQL code.
20120 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .*/./***********
20130 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
20140 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
20150 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 3rd ***********
20160 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a * 4th **********
20170 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20180 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 E_CREATE_INDEX
20190 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 1 /* I
201a0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
201b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
201c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
201d0 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 _CREATE_TABLE
201e0 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 2 /* Ta
201f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
20200 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
20210 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20220 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 CREATE_TEMP_INDE
20230 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 X 3 /* Ind
20240 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
20250 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
20260 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
20270 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 REATE_TEMP_TABLE
20280 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 4 /* Tabl
20290 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
202a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
202b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
202c0 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 EATE_TEMP_TRIGGE
202d0 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 R 5 /* Trigg
202e0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
202f0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
20300 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
20310 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 ATE_TEMP_VIEW
20320 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 6 /* View N
20330 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
20340 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
20350 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
20360 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 TE_TRIGGER
20370 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 7 /* Trigger
20380 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
20390 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
203a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
203b0 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 E_VIEW
203c0 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 8 /* View Nam
203d0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
203e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
203f0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 ne SQLITE_DELETE
20400 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20410 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 9 /* Table Nam
20420 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
20430 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
20440 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e e SQLITE_DROP_IN
20450 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 DEX 10
20460 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
20470 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
20480 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
20490 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 SQLITE_DROP_TAB
204a0 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 LE 11
204b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
204c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
204d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
204e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
204f0 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 _INDEX 12
20500 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
20510 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
20520 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
20530 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
20540 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 TABLE 13
20550 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
20560 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
20570 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20580 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 LITE_DROP_TEMP_T
20590 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f RIGGER 14 /
205a0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
205b0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
205c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
205d0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 ITE_DROP_TEMP_VI
205e0 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a EW 15 /*
205f0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
20600 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
20610 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20620 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 TE_DROP_TRIGGER
20630 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 16 /*
20640 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
20650 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
20660 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20670 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 E_DROP_VIEW
20680 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 17 /* V
20690 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
206a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
206b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
206c0 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 _INSERT
206d0 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 18 /* Ta
206e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
206f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
20700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20710 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 PRAGMA
20720 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 19 /* Pra
20730 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 gma Name 1st
20740 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a arg or NULL */.
20750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
20760 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 EAD
20770 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 20 /* Tabl
20780 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 e Name Colu
20790 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 mn Name */.#
207a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 define SQLITE_SE
207b0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 LECT
207c0 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 21 /* NULL
207d0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 NULL
207e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
207f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 efine SQLITE_TRA
20800 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 NSACTION
20810 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 22 /* Operat
20820 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ion NULL
20830 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
20840 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 fine SQLITE_UPDA
20850 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
20860 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 23 /* Table N
20870 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 ame Column
20880 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
20890 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 ine SQLITE_ATTAC
208a0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
208b0 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 24 /* Filename
208c0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 NULL
208d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
208e0 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 ne SQLITE_DETACH
208f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
20900 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 5 /* Database
20910 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 Name NULL
20920 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
20930 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 e SQLITE_ALTER_T
20940 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 ABLE 26
20950 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e /* Database N
20960 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 ame Table Name
20970 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
20980 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 SQLITE_REINDEX
20990 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 27
209a0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
209b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
209c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
209d0 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 SQLITE_ANALYZE
209e0 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 28
209f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
20a00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
20a10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
20a20 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 QLITE_CREATE_VTA
20a30 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 BLE 29
20a40 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
20a50 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 Module Name
20a60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20a70 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 LITE_DROP_VTABLE
20a80 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 30 /
20a90 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
20aa0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 Module Name
20ab0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
20ac0 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 ITE_FUNCTION
20ad0 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 31 /*
20ae0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
20af0 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 Function Name
20b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20b10 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 TE_SAVEPOINT
20b20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 32 /*
20b30 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 Operation
20b40 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 Savepoint Name
20b50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20b60 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 E_COPY
20b70 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 0 /* N
20b80 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f o longer used */
20b90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20ba0 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 RECURSIVE
20bb0 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 33 /* NUL
20bc0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c L NUL
20bd0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
20be0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
20bf0 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f Tracing And Pro
20c00 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 filing Functions
20c10 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
20c20 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 te3.**.** These
20c30 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 routines registe
20c40 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 r callback funct
20c50 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 ions that can be
20c60 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 used for.** tra
20c70 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 cing and profili
20c80 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e ng the execution
20c90 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e of SQL statemen
20ca0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 ts..**.** ^The c
20cb0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
20cc0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 registered by s
20cd0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 qlite3_trace() i
20ce0 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 s invoked at.**
20cf0 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 various times wh
20d00 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d en an SQL statem
20d10 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e ent is being run
20d20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 by [sqlite3_ste
20d30 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 p()]..** ^The sq
20d40 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 lite3_trace() ca
20d50 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
20d60 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 d with a UTF-8 r
20d70 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a endering of the.
20d80 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
20d90 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 text as the sta
20da0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 tement first beg
20db0 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a ins executing..*
20dc0 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 * ^(Additional s
20dd0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 qlite3_trace() c
20de0 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f allbacks might o
20df0 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 ccur.** as each
20e00 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f triggered subpro
20e10 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e gram is entered.
20e20 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 The callbacks
20e30 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 for triggers.**
20e40 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 contain a UTF-8
20e50 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 SQL comment that
20e60 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 identifies the
20e70 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a trigger.)^.**.**
20e80 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 The [SQLITE_TRA
20e90 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 CE_SIZE_LIMIT] c
20ea0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
20eb0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 on can be used t
20ec0 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c o limit.** the l
20ed0 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 ength of [bound
20ee0 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e parameter] expan
20ef0 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 sion in the outp
20f00 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 ut of sqlite3_tr
20f10 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ace()..**.** ^Th
20f20 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
20f30 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
20f40 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c y sqlite3_profil
20f50 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
20f60 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 * as each SQL st
20f70 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 atement finishes
20f80 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 . ^The profile
20f90 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e callback contain
20fa0 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 s.** the origina
20fb0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 l statement text
20fc0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 and an estimate
20fd0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 of wall-clock t
20fe0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f ime.** of how lo
20ff0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e ng that statemen
21000 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 t took to run.
21010 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c ^The profile cal
21020 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 lback.** time is
21030 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e in units of nan
21040 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 oseconds, howeve
21050 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d r the current im
21060 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 plementation.**
21070 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 is only capable
21080 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 of millisecond r
21090 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 esolution so the
210a0 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 six least signi
210b0 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 ficant.** digits
210c0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 in the time are
210d0 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 meaningless. F
210e0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
210f0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 f SQLite.** migh
21100 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 t provide greate
21110 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 r resolution on
21120 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c the profiler cal
21130 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 lback. The.** s
21140 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 qlite3_profile()
21150 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e function is con
21160 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 sidered experime
21170 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 ntal and is.** s
21180 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
21190 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 in future versi
211a0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ons of SQLite..*
211b0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
211c0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
211d0 4c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 L sqlite3_trace(
211e0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a sqlite3*, void(*
211f0 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f xTrace)(void*,co
21200 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 nst char*), void
21210 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 *);.SQLITE_API S
21220 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
21230 41 4c 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f AL void *SQLITE_
21240 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
21250 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a profile(sqlite3*
21260 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 ,. void(*xProf
21270 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ile)(void*,const
21280 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 char*,sqlite3_u
21290 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a int64), void*);.
212a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
212b0 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 Query Progress
212c0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 Callbacks.** MET
212d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
212e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
212f0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 progress_handler
21300 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 (D,N,X,P) interf
21310 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 ace causes the c
21320 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
21330 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f ion X to be invo
21340 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 ked periodically
21350 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e during long run
21360 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a ning calls to.**
21370 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
21380 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ], [sqlite3_step
21390 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
213a0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f _get_table()] fo
213b0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
213c0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 nnection D. An
213d0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 example use for
213e0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 this.** interfac
213f0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 e is to keep a G
21400 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e UI updated durin
21410 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e g a large query.
21420 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 .**.** ^The para
21430 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 meter P is passe
21440 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 d through as the
21450 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 only parameter
21460 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 to the .** callb
21470 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 ack function X.
21480 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 ^The parameter
21490 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 N is the approxi
214a0 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a mate number of .
214b0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 ** [virtual mach
214c0 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 ine instructions
214d0 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 ] that are evalu
214e0 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 ated between suc
214f0 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 cessive.** invoc
21500 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 ations of the ca
21510 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e llback X. ^If N
21520 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e is less than on
21530 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 e then the progr
21540 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 ess.** handler i
21550 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a s disabled..**.*
21560 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 * ^Only a single
21570 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
21580 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 r may be defined
21590 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 at one time per
215a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
215b0 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 nnection]; setti
215c0 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 ng a new progres
215d0 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c s handler cancel
215e0 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 s the.** old one
215f0 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 . ^Setting para
21600 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 meter X to NULL
21610 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f disables the pro
21620 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a gress handler..*
21630 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 * ^The progress
21640 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 handler is also
21650 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 disabled by sett
21660 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 ing N to a value
21670 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e less.** than 1.
21680 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 .**.** ^If the p
21690 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
216a0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
216b0 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e o, the operation
216c0 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 is.** interrupt
216d0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 ed. This featur
216e0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
216f0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 implement a.**
21700 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 "Cancel" button
21710 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 on a GUI progres
21720 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a s dialog box..**
21730 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 .** The progress
21740 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
21750 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e k must not do an
21760 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
21770 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
21780 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
21790 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
217a0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e the progress han
217b0 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 dler..** Note th
217c0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
217d0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
217e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
217f0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
21800 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
21810 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
21820 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
21830 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
21840 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 agraph..**.*/.SQ
21850 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 LITE_API void SQ
21860 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
21870 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 ite3_progress_ha
21880 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 ndler(sqlite3*,
21890 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 int, int(*)(void
218a0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a *), void*);../*.
218b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 ** CAPI3REF: Ope
218c0 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 ning A New Datab
218d0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase Connection.*
218e0 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 * CONSTRUCTOR: s
218f0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
21900 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 ese routines ope
21910 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 n an SQLite data
21920 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 base file as spe
21930 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a cified by the .*
21940 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d * filename argum
21950 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 ent. ^The filena
21960 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 me argument is i
21970 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 nterpreted as UT
21980 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 F-8 for.** sqlit
21990 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
219a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
219b0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e and as UTF-16 in
219c0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
219d0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 .** order for sq
219e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 lite3_open16().
219f0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f ^(A [database co
21a00 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
21a10 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 is usually.** r
21a20 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 eturned in *ppDb
21a30 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 , even if an err
21a40 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 or occurs. The
21a50 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 only exception i
21a60 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c s that.** if SQL
21a70 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ite is unable to
21a80 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
21a90 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 to hold the [sq
21aa0 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a lite3] object,.*
21ab0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 * a NULL will be
21ac0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
21ad0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 pDb instead of a
21ae0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
21af0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a [sqlite3].** obj
21b00 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 ect.)^ ^(If the
21b10 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
21b20 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 ed (and/or creat
21b30 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 ed) successfully
21b40 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 , then.** [SQLIT
21b50 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 E_OK] is returne
21b60 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e d. Otherwise an
21b70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
21b80 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 returned.)^ ^Th
21b90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 e.** [sqlite3_er
21ba0 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 rmsg()] or [sqli
21bb0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 te3_errmsg16()]
21bc0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 routines can be
21bd0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a used to obtain.*
21be0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e * an English lan
21bf0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f guage descriptio
21c00 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 n of the error f
21c10 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 ollowing a failu
21c20 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 re of any.** of
21c30 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e the sqlite3_open
21c40 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a () routines..**.
21c50 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 ** ^The default
21c60 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 encoding will be
21c70 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 UTF-8 for datab
21c80 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69 ases created usi
21c90 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 ng.** sqlite3_op
21ca0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f en() or sqlite3_
21cb0 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 open_v2(). ^The
21cc0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e default encodin
21cd0 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a g for databases.
21ce0 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 ** created using
21cf0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
21d00 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 ) will be UTF-16
21d10 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 in the native b
21d20 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a yte order..**.**
21d30 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 Whether or not
21d40 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
21d50 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 when it is opene
21d60 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 d, resources.**
21d70 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
21d80 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
21d90 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
21da0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 should be relea
21db0 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e sed by.** passin
21dc0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 g it to [sqlite3
21dd0 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 _close()] when i
21de0 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 t is no longer r
21df0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 equired..**.** T
21e00 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f he sqlite3_open_
21e10 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 v2() interface w
21e20 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 orks like sqlite
21e30 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 3_open().** exce
21e40 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 pt that it accep
21e50 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 ts two additiona
21e60 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 l parameters for
21e70 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 additional cont
21e80 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 rol.** over the
21e90 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e new database con
21ea0 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 nection. ^(The
21eb0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
21ec0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 to.** sqlite3_op
21ed0 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 en_v2() can take
21ee0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 one of.** the f
21ef0 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 ollowing three v
21f00 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c alues, optionall
21f10 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 y combined with
21f20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the .** [SQLITE_
21f30 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b OPEN_NOMUTEX], [
21f40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c SQLITE_OPEN_FULL
21f50 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f MUTEX], [SQLITE_
21f60 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
21f70 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 ],.** [SQLITE_OP
21f80 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d EN_PRIVATECACHE]
21f90 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 , and/or [SQLITE
21fa0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 _OPEN_URI] flags
21fb0 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a :)^.**.** <dl>.*
21fc0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f * ^(<dt>[SQLITE_
21fd0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f OPEN_READONLY]</
21fe0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
21ff0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
22000 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d d in read-only m
22010 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 ode. If the dat
22020 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a abase does not.*
22030 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c * already exist,
22040 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 an error is ret
22050 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a urned.</dd>)^.**
22060 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 .** ^(<dt>[SQLIT
22070 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
22080 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 ]</dt>.** <dd>Th
22090 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
220a0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 ened for reading
220b0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 and writing if
220c0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 possible, or rea
220d0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 ding.** only if
220e0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 the file is writ
220f0 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 e protected by t
22100 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
22110 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a tem. In either.
22120 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 ** case the data
22130 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 base must alread
22140 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 y exist, otherwi
22150 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 se an error is r
22160 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a eturned.</dd>)^.
22170 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c **.** ^(<dt>[SQL
22180 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
22190 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 TE] | [SQLITE_OP
221a0 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a EN_CREATE]</dt>.
221b0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 ** <dd>The datab
221c0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f ase is opened fo
221d0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 r reading and wr
221e0 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 iting, and is cr
221f0 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 eated if.** it d
22200 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 oes not already
22210 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 exist. This is t
22220 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 he behavior that
22230 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 is always used
22240 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f for.** sqlite3_o
22250 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 pen() and sqlite
22260 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 3_open16().</dd>
22270 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a )^.** </dl>.**.*
22280 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 * If the 3rd par
22290 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
222a0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 3_open_v2() is n
222b0 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a ot one of the.**
222c0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 combinations sh
222d0 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e own above option
222e0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 ally combined wi
222f0 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c th other.** [SQL
22300 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
22310 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f Y | SQLITE_OPEN_
22320 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 * bits].** then
22330 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
22340 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
22350 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 ^If the [SQLITE
22360 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 _OPEN_NOMUTEX] f
22370 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e lag is set, then
22380 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
22390 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e nnection.** open
223a0 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 s in the multi-t
223b0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 hread [threading
223c0 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 mode] as long a
223d0 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 s the single-thr
223e0 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 ead.** mode has
223f0 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 not been set at
22400 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 compile-time or
22410 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 start-time. ^If
22420 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
22430 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 OPEN_FULLMUTEX]
22440 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e flag is set then
22450 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
22460 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a nnection opens.*
22470 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 * in the seriali
22480 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d zed [threading m
22490 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 ode] unless sing
224a0 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a le-thread was.**
224b0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 previously sele
224c0 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d cted at compile-
224d0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 time or start-ti
224e0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c me..** ^The [SQL
224f0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
22500 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 ACHE] flag cause
22510 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 s the database c
22520 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a onnection to be.
22530 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 ** eligible to u
22540 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 se [shared cache
22550 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 mode], regardle
22560 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
22570 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 not shared.** c
22580 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 ache is enabled
22590 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 using [sqlite3_e
225a0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 nable_shared_cac
225b0 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 he()]. ^The.**
225c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 [SQLITE_OPEN_PRI
225d0 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 VATECACHE] flag
225e0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 causes the datab
225f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
22600 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 o not.** partici
22610 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 pate in [shared
22620 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e cache mode] even
22630 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 if it is enable
22640 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f d..**.** ^The fo
22650 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
22660 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
22670 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 2() is the name
22680 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
22690 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 e3_vfs] object t
226a0 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 hat defines the
226b0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
226c0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a interface that.
226d0 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 ** the new datab
226e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 ase connection s
226f0 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 hould use. ^If
22700 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
22710 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c eter is.** a NUL
22720 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 L pointer then t
22730 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
22740 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 te3_vfs] object
22750 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e is used..**.** ^
22760 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 If the filename
22770 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 is ":memory:", t
22780 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 hen a private, t
22790 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f emporary in-memo
227a0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 ry database.** i
227b0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 s created for th
227c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e e connection. ^
227d0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 This in-memory d
227e0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e atabase will van
227f0 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 ish when.** the
22800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
22810 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 ion is closed.
22820 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
22830 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a of SQLite might.
22840 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 ** make use of a
22850 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 dditional specia
22860 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 l filenames that
22870 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 begin with the
22880 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ":" character..*
22890 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e * It is recommen
228a0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 ded that when a
228b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d database filenam
228c0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 e actually does
228d0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 begin with.** a
228e0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f ":" character yo
228f0 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 u should prefix
22900 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 the filename wit
22910 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 h a pathname suc
22920 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 h as.** "./" to
22930 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e avoid ambiguity.
22940 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .**.** ^If the f
22950 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d ilename is an em
22960 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e pty string, then
22970 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 a private, temp
22980 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b orary.** on-disk
22990 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 database will b
229a0 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 e created. ^Thi
229b0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 s private databa
229c0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 se will be.** au
229d0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 tomatically dele
229e0 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 ted as soon as t
229f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
22a00 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 ection is closed
22a10 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 ..**.** [[URI fi
22a20 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 lenames in sqlit
22a30 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e e3_open()]] <h3>
22a40 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 URI Filenames</h
22a50 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 3>.**.** ^If [UR
22a60 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 I filename] inte
22a70 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e rpretation is en
22a80 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 abled, and the f
22a90 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
22aa0 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 .** begins with
22ab0 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 "file:", then th
22ac0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e e filename is in
22ad0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 terpreted as a U
22ae0 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 RI. ^URI.** file
22af0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 name interpretat
22b00 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 ion is enabled i
22b10 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 f the [SQLITE_OP
22b20 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a EN_URI] flag is.
22b30 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f ** set in the fo
22b40 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f urth argument to
22b50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
22b60 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 (), or if it has
22b70 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 .** been enabled
22b80 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 globally using
22b90 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 the [SQLITE_CONF
22ba0 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 IG_URI] option w
22bb0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ith the.** [sqli
22bc0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 te3_config()] me
22bd0 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b thod or by the [
22be0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 SQLITE_USE_URI]
22bf0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
22c00 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 ion..** As of SQ
22c10 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 Lite version 3.7
22c20 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 .7, URI filename
22c30 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 interpretation
22c40 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a is turned off.**
22c50 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 by default, but
22c60 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
22c70 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 of SQLite might
22c80 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 enable URI file
22c90 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 name.** interpre
22ca0 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c tation by defaul
22cb0 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 t. See "[URI fi
22cc0 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 lenames]" for ad
22cd0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f ditional.** info
22ce0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 rmation..**.** U
22cf0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 RI filenames are
22d00 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e parsed accordin
22d10 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e g to RFC 3986. ^
22d20 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 If the URI conta
22d30 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 ins an.** author
22d40 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 ity, then it mus
22d50 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 t be either an e
22d60 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 mpty string or t
22d70 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c he string .** "l
22d80 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 ocalhost". ^If t
22d90 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 he authority is
22da0 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 not an empty str
22db0 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 ing or "localhos
22dc0 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 t", an .** error
22dd0 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 is returned to
22de0 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 the caller. ^The
22df0 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e fragment compon
22e00 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 ent of a URI, if
22e10 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 .** present, is
22e20 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 ignored..**.**
22e30 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 ^SQLite uses the
22e40 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 path component
22e50 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 of the URI as th
22e60 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 e name of the di
22e70 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 sk file.** which
22e80 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 contains the da
22e90 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 tabase. ^If the
22ea0 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 path begins with
22eb0 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 a '/' character
22ec0 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 , .** then it is
22ed0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
22ee0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 an absolute path
22ef0 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 . ^If the path d
22f00 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a oes not begin .*
22f10 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 * with a '/' (me
22f20 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 aning that the a
22f30 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e uthority section
22f40 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d is omitted from
22f50 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 the URI).** the
22f60 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e n the path is in
22f70 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 terpreted as a r
22f80 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a elative path. .*
22f90 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 * ^(On windows,
22fa0 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e the first compon
22fb0 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 ent of an absolu
22fc0 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 te path .** is a
22fd0 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 drive specifica
22fe0 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 tion (e.g. "C:")
22ff0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 .)^.**.** [[core
23000 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d URI query param
23010 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 eters]].** The q
23020 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f uery component o
23030 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 f a URI may cont
23040 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 ain parameters t
23050 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 hat are interpre
23060 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 ted.** either by
23070 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 SQLite itself,
23080 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 or by a [VFS | c
23090 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d ustom VFS implem
230a0 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 entation]..** SQ
230b0 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 Lite and its bui
230c0 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e lt-in [VFSes] in
230d0 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 terpret the.** f
230e0 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 ollowing query p
230f0 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a arameters:.**.**
23100 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 <ul>.** <li>
23110 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 <b>vfs</b>: ^The
23120 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 "vfs" parameter
23130 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 may be used to
23140 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 specify the name
23150 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 of.** a VFS
23160 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f object that pro
23170 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 vides the operat
23180 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 ing system inter
23190 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 face that should
231a0 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 .** be used
231b0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 to access the da
231c0 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 tabase file on d
231d0 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 isk. ^If this op
231e0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a tion is set to.*
231f0 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 * an empty s
23200 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c tring the defaul
23210 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 t VFS object is
23220 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e used. ^Specifyin
23230 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 g an unknown.**
23240 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 VFS is an er
23250 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 ror. ^If sqlite3
23260 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 _open_v2() is us
23270 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f ed and the vfs o
23280 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 ption is.**
23290 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 present, then th
232a0 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 e VFS specified
232b0 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 by the option ta
232c0 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f kes precedence o
232d0 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 ver.** the v
232e0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 alue passed as t
232f0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
23300 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ter to sqlite3_o
23310 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 pen_v2()..**.**
23320 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f <li> <b>mode</
23330 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 b>: ^(The mode p
23340 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 arameter may be
23350 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 set to either "r
23360 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 o", "rw",.**
23370 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f "rwc", or "memo
23380 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 ry". Attempting
23390 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 to set it to any
233a0 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a other value is.
233b0 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 ** an error)
233c0 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 ^. .** ^If "
233d0 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 ro" is specified
233e0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 , then the datab
233f0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f ase is opened fo
23400 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 r read-only .**
23410 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 access, just
23420 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 as if the [SQLI
23430 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
23440 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 ] flag had been
23450 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 set in the .**
23460 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e third argumen
23470 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 t to sqlite3_ope
23480 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 n_v2(). ^If the
23490 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 mode option is s
234a0 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 et to .** "r
234b0 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 w", then the dat
234c0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
234d0 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 for read-write (
234e0 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 but not create)
234f0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 .** access,
23500 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 as if SQLITE_OPE
23510 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 N_READWRITE (but
23520 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e not SQLITE_OPEN
23530 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a _CREATE) had .**
23540 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e been set. ^
23550 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 Value "rwc" is e
23560 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 quivalent to set
23570 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 ting both .**
23580 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 SQLITE_OPEN_RE
23590 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 ADWRITE and SQLI
235a0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 TE_OPEN_CREATE.
235b0 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 ^If the mode op
235c0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 tion is.** s
235d0 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 et to "memory" t
235e0 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d hen a pure [in-m
235f0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 emory database]
23600 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 that never reads
23610 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 .** or write
23620 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 s from disk is u
23630 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 sed. ^It is an e
23640 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 rror to specify
23650 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 a value for.**
23660 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 the mode para
23670 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 meter that is le
23680 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 ss restrictive t
23690 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 han that specifi
236a0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 ed by.** the
236b0 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e flags passed in
236c0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
236d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
236e0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a open_v2()..**.**
236f0 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 <li> <b>cache
23700 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 </b>: ^The cache
23710 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
23720 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 e set to either
23730 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 "shared" or.**
23740 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 "private". ^S
23750 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 etting it to "sh
23760 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c ared" is equival
23770 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 ent to setting t
23780 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 he.** SQLITE
23790 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
237a0 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 E bit in the fla
237b0 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 gs argument pass
237c0 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c ed to.** sql
237d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 ite3_open_v2().
237e0 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 ^Setting the cac
237f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 he parameter to
23800 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a "private" is .**
23810 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 equivalent
23820 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 to setting the S
23830 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
23840 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 TECACHE bit..**
23850 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f ^If sqlite3_
23860 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 open_v2() is use
23870 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 d and the "cache
23880 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 " parameter is p
23890 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 resent in.**
238a0 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c a URI filename,
238b0 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 its value overr
238c0 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f ides any behavio
238d0 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 r requested by s
238e0 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 etting.** SQ
238f0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 LITE_OPEN_PRIVAT
23900 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 ECACHE or SQLITE
23910 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
23920 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c E flag..**.** <
23930 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a li> <b>psow</b>:
23940 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d ^The psow param
23950 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 eter indicates w
23960 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
23970 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 e.** [powers
23980 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 afe overwrite] p
23990 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 roperty does or
239a0 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 does not apply t
239b0 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f o the.** sto
239c0 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 rage media on wh
239d0 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 ich the database
239e0 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a file resides..*
239f0 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f *.** <li> <b>no
23a00 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e lock</b>: ^The n
23a10 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 olock parameter
23a20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 is a boolean que
23a30 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 ry parameter.**
23a40 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74 which if set
23a50 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c disables file l
23a60 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 ocking in rollba
23a70 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 ck journal modes
23a80 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 . This.** i
23a90 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 s useful for acc
23aa0 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 essing a databas
23ab0 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 e on a filesyste
23ac0 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a m that does not.
23ad0 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c ** support l
23ae0 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e ocking. Caution
23af0 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 : Database corr
23b00 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 uption might res
23b10 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 ult if two.**
23b20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 or more proces
23b30 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 ses write to the
23b40 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 same database a
23b50 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 nd any one of th
23b60 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 ose.** proce
23b70 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b sses uses nolock
23b80 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 =1..**.** <li>
23b90 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e <b>immutable</b>
23ba0 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 : ^The immutable
23bb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
23bc0 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a boolean query.**
23bd0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 parameter t
23be0 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 hat indicates th
23bf0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 at the database
23c00 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f file is stored o
23c10 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e n.** read-on
23c20 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e ly media. ^When
23c30 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 immutable is se
23c40 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 t, SQLite assume
23c50 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 s that the.**
23c60 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 database file
23c70 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 cannot be change
23c80 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f d, even by a pro
23c90 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72 cess with higher
23ca0 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 .** privileg
23cb0 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 e, and so the da
23cc0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
23cd0 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 read-only and a
23ce0 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 ll locking.**
23cf0 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 and change det
23d00 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c ection is disabl
23d10 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 ed. Caution: Se
23d20 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 tting the immuta
23d30 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 ble.** prope
23d40 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 rty on a databas
23d50 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 e file that does
23d60 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 in fact change
23d70 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 can result.**
23d80 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 in incorrect q
23d90 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 uery results and
23da0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 /or [SQLITE_CORR
23db0 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 UPT] errors..**
23dc0 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 See also: [S
23dd0 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 QLITE_IOCAP_IMMU
23de0 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 TABLE]..**
23df0 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a .** </ul>.**.**
23e00 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 ^Specifying an
23e10 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 unknown paramete
23e20 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 r in the query c
23e30 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 omponent of a UR
23e40 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 I is not an.** e
23e50 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 rror. Future ve
23e60 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
23e70 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e might understan
23e80 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 d additional que
23e90 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 ry.** parameters
23ea0 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 . See "[query p
23eb0 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 arameters with s
23ec0 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 pecial meaning t
23ed0 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a o SQLite]" for.*
23ee0 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 * additional inf
23ef0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
23f00 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 [[URI filename e
23f10 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 xamples]] <h3>UR
23f20 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 I filename examp
23f30 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c les</h3>.**.** <
23f40 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 table border="1"
23f50 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 align=center ce
23f60 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 llpadding=5>.**
23f70 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c <tr><th> URI fil
23f80 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 enames <th> Resu
23f90 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 lts.** <tr><td>
23fa0 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 file:data.db <td
23fb0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f > .** O
23fc0 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 pen the file "da
23fd0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 ta.db" in the cu
23fe0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e rrent directory.
23ff0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
24000 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 e:/home/fred/dat
24010 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 a.db<br>.**
24020 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d file:///hom
24030 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c e/fred/data.db <
24040 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 br> .**
24050 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 file://localhos
24060 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 t/home/fred/data
24070 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a .db <br> <td> .*
24080 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 * Open
24090 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
240a0 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 e "/home/fred/da
240b0 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c ta.db"..** <tr><
240c0 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 td> file://darks
240d0 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 tar/home/fred/da
240e0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 ta.db <td> .**
240f0 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 An error
24100 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 . "darkstar" is
24110 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 not a recognized
24120 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c authority..** <
24130 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 tr><td style="wh
24140 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 ite-space:nowrap
24150 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 "> .**
24160 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d file:///C:/Docum
24170 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 ents%20and%20Set
24180 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 tings/fred/Deskt
24190 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 op/data.db.**
241a0 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f <td> Windows o
241b0 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 nly: Open the fi
241c0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 le "data.db" on
241d0 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f fred's desktop o
241e0 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 n drive.**
241f0 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 C:. Note tha
24200 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 t the %20 escapi
24210 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 ng in this examp
24220 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 le is not strict
24230 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ly .**
24240 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 necessary - spac
24250 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e e characters can
24260 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c be used literal
24270 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 ly.** i
24280 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e n URI filenames.
24290 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
242a0 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 e:data.db?mode=r
242b0 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 o&cache=private
242c0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <td> .**
242d0 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 Open file "dat
242e0 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 a.db" in the cur
242f0 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 rent directory f
24300 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 or read-only acc
24310 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 ess..**
24320 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 Regardless of w
24330 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 hether or not sh
24340 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 ared-cache mode
24350 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a is enabled by.**
24360 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c defaul
24370 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 t, use a private
24380 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c cache..** <tr><
24390 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 td> file:/home/f
243a0 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d red/data.db?vfs=
243b0 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 unix-dotfile <td
243c0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 >.** Op
243d0 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 en file "/home/f
243e0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 red/data.db". Us
243f0 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 e the special VF
24400 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 S "unix-dotfile"
24410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 .** tha
24420 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 t uses dot-files
24430 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 in place of pos
24440 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b ix advisory lock
24450 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ing..** <tr><td>
24460 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f file:data.db?mo
24470 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e de=readonly <td>
24480 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e .** An
24490 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c error. "readonl
244a0 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 y" is not a vali
244b0 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 d option for the
244c0 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 "mode" paramete
244d0 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a r..** </table>.*
244e0 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 *.** ^URI hexade
244f0 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 cimal escape seq
24500 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 uences (%HH) are
24510 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 supported withi
24520 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a n the path and.*
24530 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e * query componen
24540 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 ts of a URI. A h
24550 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 exadecimal escap
24560 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 e sequence consi
24570 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 sts of a.** perc
24580 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d ent sign - "%" -
24590 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 followed by exa
245a0 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 ctly two hexadec
245b0 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 imal digits .**
245c0 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 specifying an oc
245d0 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f tet value. ^Befo
245e0 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 re the path or q
245f0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 uery components
24600 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 of a.** URI file
24610 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 name are interpr
24620 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 eted, they are e
24630 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 ncoded using UTF
24640 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 -8 and all .** h
24650 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 exadecimal escap
24660 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c e sequences repl
24670 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 aced by a single
24680 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 byte containing
24690 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f the.** correspo
246a0 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 nding octet. If
246b0 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e this process gen
246c0 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 erates an invali
246d0 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 d UTF-8 encoding
246e0 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 ,.** the results
246f0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
24700 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f **.** <b>Note to
24710 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c Windows users:<
24720 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e /b> The encodin
24730 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 g used for the f
24740 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
24750 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f .** of sqlite3_o
24760 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 pen() and sqlite
24770 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 3_open_v2() must
24780 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 be UTF-8, not w
24790 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 hatever.** codep
247a0 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 age is currently
247b0 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e defined. Filen
247c0 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ames containing
247d0 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a international.**
247e0 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 characters must
247f0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f be converted to
24800 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 UTF-8 prior to
24810 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 passing them int
24820 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 o.** sqlite3_ope
24830 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f n() or sqlite3_o
24840 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 pen_v2()..**.**
24850 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f <b>Note to Windo
24860 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 ws Runtime users
24870 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f :</b> The tempo
24880 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d rary directory m
24890 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 ust be set.** pr
248a0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 ior to calling s
248b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 qlite3_open() or
248c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
248d0 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 (). Otherwise,
248e0 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 various.** featu
248f0 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 res that require
24900 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 the use of temp
24910 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 orary files may
24920 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 fail..**.** See
24930 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 also: [sqlite3_t
24940 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a emp_directory].*
24950 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
24960 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
24970 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 sqlite3_open(.
24980 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 const char *file
24990 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
249a0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
249b0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 F-8) */. sqlite
249c0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 3 **ppDb
249d0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
249e0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b db handle */.);
249f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
24a00 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
24a10 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 qlite3_open16(.
24a20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c const void *fil
24a30 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
24a40 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
24a50 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 TF-16) */. sqli
24a60 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
24a70 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
24a80 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
24a90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
24aa0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
24ab0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
24ac0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a (. const char *
24ad0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 filename, /* D
24ae0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
24af0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 (UTF-8) */. sq
24b00 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 lite3 **ppDb,
24b10 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
24b20 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
24b30 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 /. int flags,
24b40 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 /* F
24b50 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 lags */. const
24b60 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 char *zVfs
24b70 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 /* Name of VFS
24b80 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a module to use *
24b90 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
24ba0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 3REF: Obtain Val
24bb0 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 ues For URI Para
24bc0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 meters.**.** The
24bd0 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 se are utility r
24be0 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 outines, useful
24bf0 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 to VFS implement
24c00 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 ations, that che
24c10 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 ck.** to see if
24c20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 a database file
24c30 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 was a URI that c
24c40 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 ontained a speci
24c50 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 fic query .** pa
24c60 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 rameter, and if
24c70 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 so obtains the v
24c80 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 alue of that que
24c90 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a ry parameter..**
24ca0 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 .** If F is the
24cb0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d database filenam
24cc0 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 e pointer passed
24cd0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 into the xOpen(
24ce0 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 ) method of .**
24cf0 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 a VFS implementa
24d00 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c tion when the fl
24d10 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f ags parameter to
24d20 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 xOpen() has one
24d30 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 or .** more of
24d40 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
24d50 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 _URI] or [SQLITE
24d60 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 _OPEN_MAIN_DB] b
24d70 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 its set and.** P
24d80 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
24d90 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 the query parame
24da0 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c ter, then.** sql
24db0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 ite3_uri_paramet
24dc0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 er(F,P) returns
24dd0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
24de0 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 P.** parameter
24df0 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 if it exists or
24e00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
24e10 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 f P does not app
24e20 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 ear as a .** que
24e30 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 ry parameter on
24e40 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 F. If P is a qu
24e50 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 ery parameter of
24e60 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 F.** has no exp
24e70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 licit value, the
24e80 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 n sqlite3_uri_pa
24e90 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 rameter(F,P) ret
24ea0 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 urns.** a pointe
24eb0 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 r to an empty st
24ec0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ring..**.** The
24ed0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c sqlite3_uri_bool
24ee0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 ean(F,P,B) routi
24ef0 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 ne assumes that
24f00 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a P is a boolean.*
24f10 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 * parameter and
24f20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 returns true (1)
24f30 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 or false (0) ac
24f40 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 cording to the v
24f50 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 alue.** of P. T
24f60 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 he sqlite3_uri_b
24f70 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f oolean(F,P,B) ro
24f80 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 utine returns tr
24f90 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a ue (1) if the.**
24fa0 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 value of query
24fb0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f parameter P is o
24fc0 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 ne of "yes", "tr
24fd0 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 ue", or "on" in
24fe0 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 any.** case or i
24ff0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 f the value begi
25000 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 ns with a non-ze
25010 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 ro number. The
25020 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f .** sqlite3_uri_
25030 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 boolean(F,P,B) r
25040 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 outines returns
25050 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 false (0) if the
25060 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 value of.** que
25070 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 ry parameter P i
25080 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 s one of "no", "
25090 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 false", or "off"
250a0 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a in any case or.
250b0 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 ** if the value
250c0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 begins with a nu
250d0 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 meric zero. If
250e0 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 P is not a query
250f0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e .** parameter on
25100 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c F or if the val
25110 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 ue of P is does
25120 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 not match any of
25130 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 the.** above, t
25140 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f hen sqlite3_uri_
25150 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 boolean(F,P,B) r
25160 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a eturns (B!=0)..*
25170 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
25180 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 _uri_int64(F,P,D
25190 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 ) routine conver
251a0 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ts the value of
251b0 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 P into a.** 64-b
251c0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
251d0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 r and returns th
251e0 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 at integer, or D
251f0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a if P does not.*
25200 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 * exist. If the
25210 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 value of P is s
25220 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 omething other t
25230 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 han an integer,
25240 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 then.** zero is
25250 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a returned..** .**
25260 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 If F is a NULL
25270 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 pointer, then sq
25280 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 lite3_uri_parame
25290 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 ter(F,P) returns
252a0 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c NULL and.** sql
252b0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e ite3_uri_boolean
252c0 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 (F,P,B) returns
252d0 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 B. If F is not
252e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 a NULL pointer a
252f0 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 nd.** is not a d
25300 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 atabase file pat
25310 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 hname pointer th
25320 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 at SQLite passed
25330 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a into the xOpen.
25340 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 ** VFS method, t
25350 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
25360 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
25370 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e is undefined an
25380 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e d probably.** un
25390 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 desirable..*/.SQ
253a0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
253b0 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 har *SQLITE_STDC
253c0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69 5f ALL sqlite3_uri_
253d0 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 parameter(const
253e0 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c char *zFilename,
253f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 const char *zPa
25400 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ram);.SQLITE_API
25410 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
25420 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69 5f ALL sqlite3_uri_
25430 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 boolean(const ch
25440 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 ar *zFile, const
25450 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 char *zParam, i
25460 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 nt bDefault);.SQ
25470 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
25480 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 _int64 SQLITE_ST
25490 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 DCALL sqlite3_ur
254a0 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 i_int64(const ch
254b0 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a ar*, const char*
254c0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 , sqlite3_int64)
254d0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
254e0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 EF: Error Codes
254f0 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 And Messages.**
25500 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
25510 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
25520 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 st recent sqlite
25530 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 3_* API call ass
25540 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a ociated with .**
25550 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
25560 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c ction] D failed,
25570 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 then the sqlite
25580 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 3_errcode(D) int
25590 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e erface.** return
255a0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 s the numeric [r
255b0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b esult code] or [
255c0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
255d0 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a code] for that.*
255e0 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 * API call..** I
255f0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
25600 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73 t API call was s
25610 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 uccessful,.** th
25620 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 en the return va
25630 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
25640 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e _errcode() is un
25650 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 defined..** ^The
25660 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
25670 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 d_errcode().** i
25680 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 nterface is the
25690 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 same except that
256a0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 it always retur
256b0 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 ns the .** [exte
256c0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
256d0 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 ] even when exte
256e0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
256f0 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 s are.** disable
25700 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
25710 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 lite3_errmsg() a
25720 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 nd sqlite3_errms
25730 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 g16() return Eng
25740 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a lish-language.**
25750 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 text that descr
25760 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 ibes the error,
25770 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 as either UTF-8
25780 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 or UTF-16 respec
25790 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d tively..** ^(Mem
257a0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ory to hold the
257b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 error message st
257c0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 ring is managed
257d0 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 internally..** T
257e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
257f0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
25800 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 worry about free
25810 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a ing the result..
25820 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 ** However, the
25830 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 error string mig
25840 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 ht be overwritte
25850 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 n or deallocated
25860 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e by.** subsequen
25870 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 t calls to other
25880 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
25890 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a e functions.)^.*
258a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
258b0 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 3_errstr() inter
258c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
258d0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 English-languag
258e0 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 e text.** that d
258f0 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 escribes the [re
25900 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 sult code], as U
25910 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 TF-8..** ^(Memor
25920 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 y to hold the er
25930 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 ror message stri
25940 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e ng is managed in
25950 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 ternally.** and
25960 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 must not be free
25970 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 d by the applica
25980 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 tion)^..**.** Wh
25990 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 en the serialize
259a0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 d [threading mod
259b0 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 e] is in use, it
259c0 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a might be the.**
259d0 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 case that a sec
259e0 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ond error occurs
259f0 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 on a separate t
25a00 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e hread in between
25a10 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 .** the time of
25a20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 the first error
25a30 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 and the call to
25a40 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
25a50 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 ..** When that h
25a60 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f appens, the seco
25a70 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 nd error will be
25a80 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 reported since
25a90 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 these.** interfa
25aa0 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 ces always repor
25ab0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e t the most recen
25ac0 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 t result. To av
25ad0 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 oid.** this, eac
25ae0 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 h thread can obt
25af0 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 ain exclusive us
25b00 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 e of the [databa
25b10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
25b20 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 .** by invoking
25b30 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 [sqlite3_mutex_e
25b40 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 nter]([sqlite3_d
25b50 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 b_mutex](D)) bef
25b60 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a ore beginning.**
25b70 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e to use D and in
25b80 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f voking [sqlite3_
25b90 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 mutex_leave]([sq
25ba0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 lite3_db_mutex](
25bb0 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c D)) after.** all
25bc0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e calls to the in
25bd0 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 terfaces listed
25be0 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 here are complet
25bf0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 ed..**.** If an
25c00 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 interface fails
25c10 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 with SQLITE_MISU
25c20 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 SE, that means t
25c30 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 he interface.**
25c40 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f was invoked inco
25c50 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 rrectly by the a
25c60 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 pplication. In
25c70 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a that case, the.*
25c80 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 * error code and
25c90 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 message may or
25ca0 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a may not be set..
25cb0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
25cc0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
25cd0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
25ce0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 (sqlite3 *db);.S
25cf0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
25d00 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
25d10 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 ite3_extended_er
25d20 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 rcode(sqlite3 *d
25d30 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 b);.SQLITE_API c
25d40 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 onst char *SQLIT
25d50 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
25d60 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 3_errmsg(sqlite3
25d70 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 *);.SQLITE_API c
25d80 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 onst void *SQLIT
25d90 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
25da0 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 3_errmsg16(sqlit
25db0 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 e3*);.SQLITE_API
25dc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
25dd0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
25de0 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b te3_errstr(int);
25df0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
25e00 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 : Prepared State
25e10 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b ment Object.** K
25e20 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 EYWORDS: {prepar
25e30 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 ed statement} {p
25e40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
25e50 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 ts}.**.** An ins
25e60 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
25e70 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 ject represents
25e80 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 a single SQL sta
25e90 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 tement that.** h
25ea0 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 as been compiled
25eb0 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 into binary for
25ec0 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 m and is ready t
25ed0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a o be evaluated..
25ee0 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 **.** Think of e
25ef0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ach SQL statemen
25f00 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20 t as a separate
25f10 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d computer program
25f20 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e . The.** origin
25f30 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 al SQL text is s
25f40 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 ource code. A p
25f50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
25f60 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 t object .** is
25f70 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a the compiled obj
25f80 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 ect code. All S
25f90 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 QL must be conve
25fa0 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 rted into a.** p
25fb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
25fc0 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 t before it can
25fd0 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 be run..**.** Th
25fe0 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 e life-cycle of
25ff0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
26000 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 ment object usua
26010 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 lly goes like th
26020 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a is:.**.** <ol>.*
26030 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 * <li> Create th
26040 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
26050 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e ment object usin
26060 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
26070 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 re_v2()]..** <li
26080 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f > Bind values to
26090 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 [parameters] us
260a0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
260b0 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 bind_*().**
260c0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
260d0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c <li> Run the SQL
260e0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
260f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 ite3_step()] one
26100 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a or more times..
26110 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 ** <li> Reset th
26120 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
26130 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ment using [sqli
26140 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 te3_reset()] the
26150 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 n go back.**
26160 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f to step 2. Do
26170 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f this zero or mo
26180 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 re times..** <li
26190 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 > Destroy the ob
261a0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ject using [sqli
261b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e te3_finalize()].
261c0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 .** </ol>.*/.typ
261d0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
261e0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 te3_stmt sqlite3
261f0 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 _stmt;../*.** CA
26200 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 PI3REF: Run-time
26210 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f Limits.** METHO
26220 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
26230 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 ^(This interfac
26240 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a e allows the siz
26250 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e e of various con
26260 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 structs to be li
26270 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f mited.** on a co
26280 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e nnection by conn
26290 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 ection basis. T
262a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
262b0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 er is the.** [da
262c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
262d0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 n] whose limit i
262e0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 s to be set or q
262f0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 ueried. The.**
26300 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
26310 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b is one of the [
26320 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
26330 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a ] that define a.
26340 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 ** class of cons
26350 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a tructs to be siz
26360 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 e limited. The
26370 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
26380 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 is the.** new li
26390 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e mit for that con
263a0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 struct.)^.**.**
263b0 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 ^If the new limi
263c0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 t is a negative
263d0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 number, the limi
263e0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a t is unchanged..
263f0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 ** ^(For each li
26400 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c mit category SQL
26410 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d ITE_LIMIT_<i>NAM
26420 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 E</i> there is a
26430 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 .** [limits | h
26440 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d ard upper bound]
26450 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 .** set at compi
26460 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 le-time by a C p
26470 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
26480 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d o called.** [lim
26490 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 its | SQLITE_MAX
264a0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a _<i>NAME</i>]..*
264b0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 * (The "_LIMIT_"
264c0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 in the name is
264d0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 changed to "_MAX
264e0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d _".))^.** ^Attem
264f0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 pts to increase
26500 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 a limit above it
26510 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 s hard upper bou
26520 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 nd are.** silent
26530 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 ly truncated to
26540 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 the hard upper b
26550 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 ound..**.** ^Reg
26560 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
26570 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 er or not the li
26580 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c mit was changed,
26590 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 the .** [sqlite
265a0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 3_limit()] inter
265b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
265c0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 prior value of
265d0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 the limit..** ^H
265e0 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 ence, to find th
265f0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 e current value
26600 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f of a limit witho
26610 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a ut changing it,.
26620 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 ** simply invoke
26630 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
26640 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 with the third p
26650 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 arameter set to
26660 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 -1..**.** Run-ti
26670 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e me limits are in
26680 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
26690 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 n applications t
266a0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f hat manage.** bo
266b0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 th their own int
266c0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 ernal database a
266d0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 nd also database
266e0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 s that are contr
266f0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 olled.** by untr
26700 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 usted external s
26710 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d ources. An exam
26720 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 ple application
26730 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 might be a.** we
26740 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 b browser that h
26750 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 as its own datab
26760 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 ases for storing
26770 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 history and.**
26780 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 separate databas
26790 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 es controlled by
267a0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c JavaScript appl
267b0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 ications downloa
267c0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 ded.** off the I
267d0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e nternet. The in
267e0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 ternal databases
267f0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 can be given th
26800 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 e.** large, defa
26810 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 ult limits. Dat
26820 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 abases managed b
26830 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 y external sourc
26840 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 es can.** be giv
26850 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 en much smaller
26860 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 limits designed
26870 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e to prevent a den
26880 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a ial of service.*
26890 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c * attack. Devel
268a0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f opers might also
268b0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 want to use the
268c0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
268d0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 thorizer()].** i
268e0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 nterface to furt
268f0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 her control untr
26900 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 usted SQL. The
26910 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 size of the data
26920 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 base.** created
26930 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 by an untrusted
26940 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f script can be co
26950 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 ntained using th
26960 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 e.** [max_page_c
26970 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a ount] [PRAGMA]..
26980 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 **.** New run-ti
26990 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 me limit categor
269a0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ies may be added
269b0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
269c0 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ses..*/.SQLITE_A
269d0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
269e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 DCALL sqlite3_li
269f0 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e mit(sqlite3*, in
26a00 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c t id, int newVal
26a10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
26a20 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d EF: Run-Time Lim
26a30 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a it Categories.**
26a40 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 KEYWORDS: {limi
26a50 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 t category} {*li
26a60 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a mit categories}.
26a70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
26a80 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 tants define var
26a90 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 ious performance
26aa0 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 limits.** that
26ab0 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 can be lowered a
26ac0 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 t run-time using
26ad0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
26ae0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 )]..** The synop
26af0 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 sis of the meani
26b00 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f ngs of the vario
26b10 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f us limits is sho
26b20 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 wn below..** Add
26b30 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
26b40 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 ion is available
26b50 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 at [limits | Li
26b60 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e mits in SQLite].
26b70 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b .**.** <dl>.** [
26b80 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 [SQLITE_LIMIT_LE
26b90 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c NGTH]] ^(<dt>SQL
26ba0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
26bb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
26bc0 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 maximum size of
26bd0 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 any string or B
26be0 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 LOB or table row
26bf0 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 , in bytes.<dd>)
26c00 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
26c10 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 _LIMIT_SQL_LENGT
26c20 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
26c30 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 _LIMIT_SQL_LENGT
26c40 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
26c50 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 e maximum length
26c60 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 of an SQL state
26c70 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c ment, in bytes.<
26c80 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
26c90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
26ca0 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 MN]] ^(<dt>SQLIT
26cb0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f E_LIMIT_COLUMN</
26cc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
26cd0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
26ce0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 columns in a ta
26cf0 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f ble definition o
26d00 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 r in the.** resu
26d10 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c lt set of a [SEL
26d20 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 ECT] or the maxi
26d30 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f mum number of co
26d40 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 lumns in an inde
26d50 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 x.** or in an OR
26d60 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 DER BY or GROUP
26d70 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 BY clause.</dd>)
26d80 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
26d90 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 _LIMIT_EXPR_DEPT
26da0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
26db0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 _LIMIT_EXPR_DEPT
26dc0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
26dd0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 e maximum depth
26de0 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 of the parse tre
26df0 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 e on any express
26e00 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ion.</dd>)^.**.*
26e10 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
26e20 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 _COMPOUND_SELECT
26e30 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
26e40 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 LIMIT_COMPOUND_S
26e50 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ELECT</dt>.** <d
26e60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
26e70 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e mber of terms in
26e80 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 a compound SELE
26e90 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 CT statement.</d
26ea0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
26eb0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f ITE_LIMIT_VDBE_O
26ec0 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 P]] ^(<dt>SQLITE
26ed0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f _LIMIT_VDBE_OP</
26ee0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
26ef0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
26f00 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e instructions in
26f10 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 a virtual machi
26f20 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 ne program.** us
26f30 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 ed to implement
26f40 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
26f50 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 . This limit is
26f60 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a not currently.*
26f70 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 * enforced, thou
26f80 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 gh that might be
26f90 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 added in some f
26fa0 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 uture release of
26fb0 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e .** SQLite.</dd>
26fc0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
26fd0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e E_LIMIT_FUNCTION
26fe0 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c _ARG]] ^(<dt>SQL
26ff0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 ITE_LIMIT_FUNCTI
27000 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c ON_ARG</dt>.** <
27010 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
27020 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e umber of argumen
27030 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e ts on a function
27040 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
27050 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 [SQLITE_LIMIT_AT
27060 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 TACHED]] ^(<dt>S
27070 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 QLITE_LIMIT_ATTA
27080 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 CHED</dt>.** <dd
27090 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
270a0 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c ber of [ATTACH |
270b0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
270c0 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a ses].)^</dd>.**.
270d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
270e0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
270f0 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 ENGTH]].** ^(<dt
27100 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 >SQLITE_LIMIT_LI
27110 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 KE_PATTERN_LENGT
27120 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
27130 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 e maximum length
27140 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 of the pattern
27150 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
27160 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c [LIKE] or.** [GL
27170 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f OB] operators.</
27180 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
27190 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
271a0 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 BLE_NUMBER]].**
271b0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
271c0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
271d0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ER</dt>.** <dd>T
271e0 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 he maximum index
271f0 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b number of any [
27200 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e parameter] in an
27210 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 SQL statement.)
27220 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
27230 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 _LIMIT_TRIGGER_D
27240 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c EPTH]] ^(<dt>SQL
27250 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 ITE_LIMIT_TRIGGE
27260 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 R_DEPTH</dt>.**
27270 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
27280 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 depth of recursi
27290 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e on for triggers.
272a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
272b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 SQLITE_LIMIT_WOR
272c0 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 KER_THREADS]] ^(
272d0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
272e0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c _WORKER_THREADS<
272f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
27300 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
27310 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b f auxiliary work
27320 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20 er threads that
27330 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 a single.** [pre
27340 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
27350 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e may start.</dd>
27360 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 )^.** </dl>.*/.#
27370 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
27380 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 MIT_LENGTH
27390 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 0.
273a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
273b0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 IMIT_SQL_LENGTH
273c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
273d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
273e0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 LIMIT_COLUMN
273f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
27400 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
27410 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 _LIMIT_EXPR_DEPT
27420 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
27430 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
27440 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 E_LIMIT_COMPOUND
27450 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 _SELECT
27460 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
27470 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 TE_LIMIT_VDBE_OP
27480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
27490 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 5.#define SQL
274a0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 ITE_LIMIT_FUNCTI
274b0 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 ON_ARG
274c0 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 6.#define SQ
274d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
274e0 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 HED
274f0 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 7.#define S
27500 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 QLITE_LIMIT_LIKE
27510 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 _PATTERN_LENGTH
27520 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 8.#define
27530 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
27540 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 IABLE_NUMBER
27550 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 9.#define
27560 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 SQLITE_LIMIT_TR
27570 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 IGGER_DEPTH
27580 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 10.#defin
27590 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 e SQLITE_LIMIT_W
275a0 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 ORKER_THREADS
275b0 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 11../*.*
275c0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 * CAPI3REF: Comp
275d0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 iling An SQL Sta
275e0 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 tement.** KEYWOR
275f0 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 DS: {SQL stateme
27600 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 nt compiler}.**
27610 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
27620 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 ** CONSTRUCTOR:
27630 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
27640 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e ** To execute an
27650 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d SQL query, it m
27660 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d ust first be com
27670 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 piled into a byt
27680 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 e-code.** progra
27690 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 m using one of t
276a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
276b0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
276c0 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 rgument, "db", i
276d0 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f s a [database co
276e0 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e nnection] obtain
276f0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 ed from a.** pri
27700 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 or successful ca
27710 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f ll to [sqlite3_o
27720 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
27730 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a _open_v2()] or.*
27740 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 * [sqlite3_open1
27750 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 6()]. The datab
27760 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d ase connection m
27770 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 ust not have bee
27780 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 n closed..**.**
27790 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
277a0 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 ent, "zSql", is
277b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f the statement to
277c0 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e be compiled, en
277d0 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 coded.** as eith
277e0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d er UTF-8 or UTF-
277f0 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 16. The sqlite3
27800 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 _prepare() and s
27810 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
27820 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2().** interface
27830 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 s use UTF-8, and
27840 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
27850 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 16() and sqlite3
27860 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a _prepare16_v2().
27870 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a ** use UTF-16..*
27880 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 *.** ^If the nBy
27890 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e te argument is n
278a0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 egative, then zS
278b0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f ql is read up to
278c0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 the.** first ze
278d0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e ro terminator. ^
278e0 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 If nByte is posi
278f0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 tive, then it is
27900 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
27910 66 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f f bytes read fro
27920 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 m zSql. ^If nBy
27930 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e te is zero, then
27940 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 no prepared.**
27950 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e statement is gen
27960 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 erated..** If th
27970 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 e caller knows t
27980 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 hat the supplied
27990 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 string is nul-t
279a0 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a erminated, then.
279b0 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 6d ** there is a sm
279c0 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 all performance
279d0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 advantage to pas
279e0 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 sing an nByte pa
279f0 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 rameter that.**
27a00 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
27a10 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e bytes in the in
27a20 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e put string <i>in
27a30 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 cluding</i>.** t
27a40 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f he nul-terminato
27a50 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 r..**.** ^If pzT
27a60 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 ail is not NULL
27a70 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 then *pzTail is
27a80 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f made to point to
27a90 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a the first byte.
27aa0 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 ** past the end
27ab0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c of the first SQL
27ac0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 statement in zS
27ad0 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 ql. These routi
27ae0 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 nes only.** comp
27af0 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 ile the first st
27b00 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c atement in zSql,
27b10 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c so *pzTail is l
27b20 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a eft pointing to.
27b30 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 ** what remains
27b40 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a uncompiled..**.*
27b50 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 * ^*ppStmt is le
27b60 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 ft pointing to a
27b70 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 compiled [prepa
27b80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
27b90 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 hat can be.** ex
27ba0 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 ecuted using [sq
27bb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 lite3_step()].
27bc0 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 ^If there is an
27bd0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 error, *ppStmt i
27be0 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c s set.** to NULL
27bf0 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 . ^If the input
27c00 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e text contains n
27c10 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e o SQL (if the in
27c20 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a put is an empty.
27c30 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 ** string or a c
27c40 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 omment) then *pp
27c50 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e Stmt is set to N
27c60 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c ULL..** The call
27c70 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 ing procedure is
27c80 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
27c90 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f deleting the co
27ca0 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 mpiled.** SQL st
27cb0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 atement using [s
27cc0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
27cd0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 )] after it has
27ce0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 finished with it
27cf0 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 ..** ppStmt may
27d00 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a not be NULL..**.
27d10 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 ** ^On success,
27d20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 the sqlite3_prep
27d30 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 are() family of
27d40 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
27d50 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 [SQLITE_OK];.**
27d60 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 otherwise an [er
27d70 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
27d80 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 urned..**.** The
27d90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
27da0 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 _v2() and sqlite
27db0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
27dc0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a interfaces are.
27dd0 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 ** recommended f
27de0 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 or all new progr
27df0 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 ams. The two old
27e00 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 er interfaces ar
27e10 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f e retained.** fo
27e20 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 r backwards comp
27e30 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 atibility, but t
27e40 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 heir use is disc
27e50 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 ouraged..** ^In
27e60 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
27e70 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 ces, the prepare
27e80 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 d statement.** t
27e90 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 hat is returned
27ea0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 (the [sqlite3_st
27eb0 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 mt] object) cont
27ec0 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 ains a copy of t
27ed0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 he.** original S
27ee0 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 QL text. This ca
27ef0 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 uses the [sqlite
27f00 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 3_step()] interf
27f10 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 ace to.** behave
27f20 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 differently in
27f30 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a three ways:.**.*
27f40 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a * <ol>.** <li>.*
27f50 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 * ^If the databa
27f60 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 se schema change
27f70 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 s, instead of re
27f80 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f turning [SQLITE_
27f90 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a SCHEMA] as it.**
27fa0 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 always used to
27fb0 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 do, [sqlite3_ste
27fc0 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 p()] will automa
27fd0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c tically recompil
27fe0 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 e the SQL.** sta
27ff0 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 tement and try t
28000 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 o run it again.
28010 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 As many as [SQLI
28020 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 TE_MAX_SCHEMA_RE
28030 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 TRY].** retries
28040 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 will occur befor
28050 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 e sqlite3_step()
28060 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 gives up and re
28070 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a turns an error..
28080 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c ** </li>.**.** <
28090 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 li>.** ^When an
280a0 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 error occurs, [s
280b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 qlite3_step()] w
280c0 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f ill return one o
280d0 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a f the detailed.*
280e0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 * [error codes]
280f0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 or [extended err
28100 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 or codes]. ^The
28110 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 legacy behavior
28120 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 was that.** [sq
28130 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f lite3_step()] wo
28140 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 uld only return
28150 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 a generic [SQLIT
28160 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 E_ERROR] result
28170 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 code.** and the
28180 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c application woul
28190 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 d have to make a
281a0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 second call to
281b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
281c0 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f ].** in order to
281d0 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c find the underl
281e0 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 ying cause of th
281f0 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 e problem. With
28200 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 the "v2" prepare
28210 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 .** interfaces,
28220 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 the underlying r
28230 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 eason for the er
28240 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 ror is returned
28250 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 immediately..**
28260 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e </li>.**.** <li>
28270 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 .** ^If the spec
28280 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 ific value bound
28290 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c to [parameter |
282a0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d host parameter]
282b0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 in the .** WHER
282c0 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 E clause might i
282d0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f nfluence the cho
282e0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 ice of query pla
282f0 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e n for a statemen
28300 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 t,.** then the s
28310 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 tatement will be
28320 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
28330 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 ecompiled, as if
28340 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 there had been
28350 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 .** a schema cha
28360 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 nge, on the firs
28370 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 t [sqlite3_step
28380 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 ()] call followi
28390 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a ng any change.**
283a0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
283b0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e _bind_text | bin
283c0 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b dings] of that [
283d0 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 parameter]. .**
283e0 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 ^The specific va
283f0 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 lue of WHERE-cla
28400 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 use [parameter]
28410 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 might influence
28420 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f the .** choice o
28430 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 f query plan if
28440 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 the parameter is
28450 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 the left-hand s
28460 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a ide of a [LIKE].
28470 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 ** or [GLOB] ope
28480 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 rator or if the
28490 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d parameter is com
284a0 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 pared to an inde
284b0 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e xed column.** an
284c0 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e d the [SQLITE_EN
284d0 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 ABLE_STAT3] comp
284e0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
284f0 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c is enabled..** <
28500 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f /li>.** </ol>.*/
28510 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
28520 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
28530 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a qlite3_prepare(.
28540 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
28550 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
28560 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
28570 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
28580 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
28590 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
285a0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 8 encoded */. i
285b0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
285c0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
285d0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
285e0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
285f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
28600 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
28610 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
28620 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
28630 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
28640 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
28650 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
28660 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 of zSql */.);.SQ
28670 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
28680 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
28690 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a te3_prepare_v2(.
286a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
286b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
286c0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
286d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
286e0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
286f0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
28700 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 8 encoded */. i
28710 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
28720 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
28730 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
28740 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
28750 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
28760 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
28770 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
28780 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
28790 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
287a0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
287b0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
287c0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 of zSql */.);.SQ
287d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
287e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
287f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 te3_prepare16(.
28800 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
28810 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
28820 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
28830 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 const void *zSq
28840 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
28850 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 statement, UTF-1
28860 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6 encoded */. i
28870 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
28880 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
28890 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
288a0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
288b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
288c0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
288d0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
288e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
288f0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
28900 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
28910 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
28920 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 of zSql */.);.SQ
28930 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
28940 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
28950 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
28960 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
28970 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
28980 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
28990 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
289a0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
289b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
289c0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a F-16 encoded */.
289d0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
289e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
289f0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
28a00 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
28a10 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
28a20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
28a30 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
28a40 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
28a50 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 oid **pzTail
28a60 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
28a70 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
28a80 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
28a90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
28aa0 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 : Retrieving Sta
28ab0 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 tement SQL.** ME
28ac0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
28ad0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 mt.**.** ^This i
28ae0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 nterface can be
28af0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 used to retrieve
28b00 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 a saved copy of
28b10 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a the original.**
28b20 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 SQL text used t
28b30 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 o create a [prep
28b40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
28b50 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e if that statemen
28b60 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 t was.** compile
28b70 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b d using either [
28b80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
28b90 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
28ba0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
28bb0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
28bc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
28bd0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
28be0 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f te3_sql(sqlite3_
28bf0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
28c00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
28c10 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 etermine If An S
28c20 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 QL Statement Wri
28c30 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 tes The Database
28c40 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
28c50 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
28c60 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 The sqlite3_stmt
28c70 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 _readonly(X) int
28c80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
28c90 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 rue (non-zero) i
28ca0 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 f.** and only if
28cb0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
28cc0 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 tatement] X make
28cd0 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e s no direct chan
28ce0 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f ges to.** the co
28cf0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 ntent of the dat
28d00 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a abase file..**.*
28d10 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 * Note that [app
28d20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
28d30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 SQL functions]
28d40 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 or.** [virtual t
28d50 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 ables] might cha
28d60 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 nge the database
28d70 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 indirectly as a
28d80 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a side effect. .
28d90 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 ** ^(For example
28da0 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 , if an applicat
28db0 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 ion defines a fu
28dc0 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 nction "eval()"
28dd0 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b that .** calls [
28de0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c sqlite3_exec()],
28df0 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 then the follow
28e00 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ing SQL statemen
28e10 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 t would.** chang
28e20 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 e the database f
28e30 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 ile through side
28e40 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 -effects:.**.**
28e50 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
28e60 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 >.** SELECT e
28e70 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d val('DELETE FROM
28e80 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a t1') FROM t2;.*
28e90 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
28ea0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 uote>.**.** But
28eb0 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c because the [SEL
28ec0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 ECT] statement d
28ed0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 oes not change t
28ee0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
28ef0 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 .** directly, sq
28f00 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f lite3_stmt_reado
28f10 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c nly() would stil
28f20 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e l return true.)^
28f30 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 .**.** ^Transact
28f40 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 ion control stat
28f50 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b ements such as [
28f60 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d BEGIN], [COMMIT]
28f70 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a , [ROLLBACK],.**
28f80 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e [SAVEPOINT], an
28f90 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 d [RELEASE] caus
28fa0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 e sqlite3_stmt_r
28fb0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 eadonly() to ret
28fc0 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e urn true,.** sin
28fd0 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 ce the statement
28fe0 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 s themselves do
28ff0 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 not actually mod
29000 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 ify the database
29010 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 but.** rather t
29020 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 hey control the
29030 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f timing of when o
29040 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 ther statements
29050 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 modify the .** d
29060 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b atabase. ^The [
29070 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 ATTACH] and [DET
29080 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 ACH] statements
29090 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 also cause.** sq
290a0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f lite3_stmt_reado
290b0 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 nly() to return
290c0 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c true since, whil
290d0 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e e those statemen
290e0 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 ts.** change the
290f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
29100 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e f a database con
29110 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f nection, they do
29120 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 not make .** ch
29130 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e anges to the con
29140 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 tent of the data
29150 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 base files on di
29160 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 sk..*/.SQLITE_AP
29170 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
29180 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d CALL sqlite3_stm
29190 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 t_readonly(sqlit
291a0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
291b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
291c0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 : Determine If A
291d0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
291e0 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 ent Has Been Res
291f0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 et.** METHOD: sq
29200 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
29210 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 ^The sqlite3_st
29220 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 mt_busy(S) inter
29230 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 face returns tru
29240 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 e (non-zero) if
29250 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
29260 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 statement] S ha
29270 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 s been stepped a
29280 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 t least once usi
29290 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ng .** [sqlite3_
292a0 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 step(S)] but has
292b0 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 neither run to
292c0 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 completion (retu
292d0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f rned.** [SQLITE_
292e0 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 DONE] from [sqli
292f0 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f te3_step(S)]) no
29300 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 r.** been reset
29310 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 using [sqlite3_r
29320 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 eset(S)]. ^The
29330 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 sqlite3_stmt_bus
29340 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 y(S).** interfac
29350 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 e returns false
29360 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 if S is a NULL p
29370 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 ointer. If S is
29380 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 not a .** NULL
29390 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e pointer and is n
293a0 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ot a pointer to
293b0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 a valid [prepare
293c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
293d0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 object, then the
293e0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
293f0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 efined and proba
29400 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e bly undesirable.
29410 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
29420 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
29430 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e d in combination
29440 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 [sqlite3_next_s
29450 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 tmt()].** to loc
29460 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 ate all prepared
29470 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f statements asso
29480 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 ciated with a da
29490 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 tabase .** conne
294a0 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 ction that are i
294b0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 n need of being
294c0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e reset. This can
294d0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 be used,.** for
294e0 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 example, in dia
294f0 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 gnostic routines
29500 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 to search for p
29510 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 repared .** stat
29520 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 ements that are
29530 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 holding a transa
29540 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 ction open..*/.S
29550 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
29560 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
29570 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 ite3_stmt_busy(s
29580 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
29590 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
295a0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 Dynamically Type
295b0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a d Value Object.*
295c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f * KEYWORDS: {pro
295d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
295e0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 alue} {unprotect
295f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
29600 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 }.**.** SQLite u
29610 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f ses the sqlite3_
29620 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 value object to
29630 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 represent all va
29640 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e lues.** that can
29650 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 be stored in a
29660 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 database table.
29670 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 SQLite uses dyna
29680 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f mic typing.** fo
29690 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 r the values it
296a0 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 stores. ^Values
296b0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 stored in sqlit
296c0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
296d0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 .** can be integ
296e0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f ers, floating po
296f0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 int values, stri
29700 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e ngs, BLOBs, or N
29710 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 ULL..**.** An sq
29720 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
29730 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 ct may be either
29740 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 "protected" or
29750 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a "unprotected"..*
29760 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 * Some interface
29770 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 s require a prot
29780 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
29790 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 lue. Other inte
297a0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 rfaces.** will a
297b0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 ccept either a p
297c0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 rotected or an u
297d0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
297e0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 e3_value..** Eve
297f0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 ry interface tha
29800 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 t accepts sqlite
29810 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 3_value argument
29820 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 s specifies.** w
29830 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 hether or not it
29840 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 requires a prot
29850 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
29860 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 lue. The.** [sq
29870 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 lite3_value_dup(
29880 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e )] interface can
29890 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 be used to cons
298a0 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 truct a new .**
298b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
298c0 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 3_value from an
298d0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
298e0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a te3_value..**.**
298f0 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 The terms "prot
29900 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 ected" and "unpr
29910 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 otected" refer t
29920 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 o whether or not
29930 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 .** a mutex is h
29940 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 eld. An interna
29950 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 l mutex is held
29960 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a for a protected.
29970 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
29980 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d object but no m
29990 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 utex is held for
299a0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a an unprotected.
299b0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
299c0 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c object. If SQL
299d0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
299e0 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 to be single-thr
299f0 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b eaded.** (with [
29a00 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
29a10 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 E=0] and with [s
29a20 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
29a30 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 e()] returning 0
29a40 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 ).** or if SQLit
29a50 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 e is run in one
29a60 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 of reduced mutex
29a70 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 modes .** [SQLI
29a80 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
29a90 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 THREAD] or [SQLI
29aa0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
29ab0 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 HREAD].** then t
29ac0 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 here is no disti
29ad0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 nction between p
29ae0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 rotected and unp
29af0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
29b00 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
29b10 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 s and they can b
29b20 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e e used interchan
29b30 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 geably. However
29b40 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d ,.** for maximum
29b50 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 code portabilit
29b60 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e y it is recommen
29b70 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 ded that applica
29b80 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d tions.** still m
29b90 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 ake the distinct
29ba0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 ion between prot
29bb0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 ected and unprot
29bc0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
29bd0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 _value objects e
29be0 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 ven when not str
29bf0 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a ictly required..
29c00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
29c10 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
29c20 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 that are passed
29c30 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 as parameters i
29c40 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 nto the.** imple
29c50 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 mentation of [ap
29c60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
29c70 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
29c80 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a are protected..
29c90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
29ca0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 value object ret
29cb0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
29cc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
29cd0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 e()] is unprotec
29ce0 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 ted..** Unprotec
29cf0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
29d00 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e e objects may on
29d10 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a ly be used with.
29d20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 ** [sqlite3_resu
29d30 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 lt_value()] and
29d40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 [sqlite3_bind_va
29d50 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b lue()]..** The [
29d60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
29d70 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c ob | sqlite3_val
29d80 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c ue_type()] famil
29d90 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 y of.** interfac
29da0 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 es require prote
29db0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
29dc0 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 ue objects..*/.t
29dd0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 ypedef struct Me
29de0 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b m sqlite3_value;
29df0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
29e00 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 : SQL Function C
29e10 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a ontext Object.**
29e20 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 .** The context
29e30 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 in which an SQL
29e40 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 function execute
29e50 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 s is stored in a
29e60 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e n.** sqlite3_con
29e70 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 text object. ^A
29e80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 pointer to an s
29e90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f qlite3_context o
29ea0 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 bject.** is alwa
29eb0 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 ys first paramet
29ec0 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 er to [applicati
29ed0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
29ee0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 unctions]..** Th
29ef0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
29f00 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
29f10 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
29f20 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 n will pass this
29f30 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f .** pointer thro
29f40 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 ugh into calls t
29f50 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c o [sqlite3_resul
29f60 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f t_int | sqlite3_
29f70 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 result()],.** [s
29f80 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
29f90 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 _context()], [sq
29fa0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
29fb0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
29fc0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
29fd0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 e()], [sqlite3_g
29fe0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a et_auxdata()],.*
29ff0 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 * and/or [sqlite
2a000 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 3_set_auxdata()]
2a010 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
2a020 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 uct sqlite3_cont
2a030 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ext sqlite3_cont
2a040 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ext;../*.** CAPI
2a050 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 3REF: Binding Va
2a060 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 lues To Prepared
2a070 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b Statements.** K
2a080 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 EYWORDS: {host p
2a090 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 arameter} {host
2a0a0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 parameters} {hos
2a0b0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 t parameter name
2a0c0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
2a0d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b SQL parameter} {
2a0e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 SQL parameters}
2a0f0 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 {parameter bindi
2a100 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ng}.** METHOD: s
2a110 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2a120 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 * ^(In the SQL s
2a130 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e tatement text in
2a140 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
2a150 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
2a160 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a d its variants,.
2a170 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 ** literals may
2a180 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 be replaced by a
2a190 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 [parameter] tha
2a1a0 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 t matches one of
2a1b0 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 following.** te
2a1c0 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c mplates:.**.** <
2a1d0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a ul>.** <li> ?.*
2a1e0 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 * <li> ?NNN.**
2a1f0 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c <li> :VVV.** <l
2a200 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e i> @VVV.** <li>
2a210 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a $VVV.** </ul>.
2a220 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d **.** In the tem
2a230 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e plates above, NN
2a240 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 N represents an
2a250 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c integer literal,
2a260 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 .** and VVV repr
2a270 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e esents an alphan
2a280 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 umeric identifie
2a290 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 r.)^ ^The value
2a2a0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 s of these.** pa
2a2b0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 rameters (also c
2a2c0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 alled "host para
2a2d0 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 meter names" or
2a2e0 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 "SQL parameters"
2a2f0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 ).** can be set
2a300 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
2a310 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
2a320 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 nes defined here
2a330 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
2a340 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
2a350 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
2a360 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 *() routines is
2a370 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e always.** a poin
2a380 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ter to the [sqli
2a390 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 te3_stmt] object
2a3a0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a returned from.*
2a3b0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
2a3c0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 re_v2()] or its
2a3d0 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 variants..**.**
2a3e0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
2a3f0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 ment is the inde
2a400 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 x of the SQL par
2a410 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 ameter to be set
2a420 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f ..** ^The leftmo
2a430 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 st SQL parameter
2a440 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 has an index of
2a450 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 1. ^When the s
2a460 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c ame named.** SQL
2a470 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 parameter is us
2a480 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 ed more than onc
2a490 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 e, second and su
2a4a0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 bsequent.** occu
2a4b0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 rrences have the
2a4c0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 same index as t
2a4d0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 he first occurre
2a4e0 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 nce..** ^The ind
2a4f0 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 ex for named par
2a500 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c ameters can be l
2a510 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 ooked up using t
2a520 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 he.** [sqlite3_b
2a530 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
2a540 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 dex()] API if de
2a550 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 sired. ^The ind
2a560 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 ex.** for "?NNN"
2a570 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 parameters is t
2a580 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e he value of NNN.
2a590 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c .** ^The NNN val
2a5a0 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 ue must be betwe
2a5b0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 en 1 and the [sq
2a5c0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a lite3_limit()].*
2a5d0 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c * parameter [SQL
2a5e0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
2a5f0 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 LE_NUMBER] (defa
2a600 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e ult value: 999).
2a610 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 .**.** ^The thir
2a620 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
2a630 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 e value to bind
2a640 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 to the parameter
2a650 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 ..** ^If the thi
2a660 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
2a670 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2a680 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 t() or sqlite3_b
2a690 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 ind_text16().**
2a6a0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f or sqlite3_bind_
2a6b0 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c blob() is a NULL
2a6c0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 pointer then th
2a6d0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2a6e0 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 er.** is ignored
2a6f0 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 and the end res
2a700 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 ult is the same
2a710 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f as sqlite3_bind_
2a720 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 null()..**.** ^(
2a730 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 In those routine
2a740 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f s that have a fo
2a750 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 urth argument, i
2a760 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a ts value is the.
2a770 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 ** number of byt
2a780 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 es in the parame
2a790 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 ter. To be clea
2a7a0 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 r: the value is
2a7b0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
2a7c0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e <u>bytes</u> in
2a7d0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 the value, not
2a7e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
2a7f0 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e aracters.)^.** ^
2a800 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
2a810 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2a820 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f e3_bind_text() o
2a830 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 r sqlite3_bind_t
2a840 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 ext16().** is ne
2a850 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 gative, then the
2a860 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 length of the s
2a870 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 tring is.** the
2a880 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2a890 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 up to the first
2a8a0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
2a8b0 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 .** If the fourt
2a8c0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
2a8d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2a8e0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 () is negative,
2a8f0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 then.** the beha
2a900 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
2a910 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e d..** If a non-n
2a920 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 egative fourth p
2a930 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 arameter is prov
2a940 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f ided to sqlite3_
2a950 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f bind_text().** o
2a960 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 r sqlite3_bind_t
2a970 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 ext16() or sqlit
2a980 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 e3_bind_text64()
2a990 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 then.** that pa
2a9a0 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 rameter must be
2a9b0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a the byte offset.
2a9c0 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c ** where the NUL
2a9d0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c terminator woul
2a9e0 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 d occur assuming
2a9f0 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 the string were
2aa00 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 NUL.** terminat
2aa10 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 ed. If any NUL
2aa20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 characters occur
2aa30 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 at byte offsets
2aa40 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 less than .** t
2aa50 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
2aa60 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
2aa70 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
2aa80 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 ing string value
2aa90 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e will.** contain
2aaa0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 embedded NULs.
2aab0 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 The result of e
2aac0 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c xpressions invol
2aad0 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 ving strings.**
2aae0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 with embedded NU
2aaf0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e Ls is undefined.
2ab00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 .**.** ^The fift
2ab10 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 h argument to th
2ab20 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e e BLOB and strin
2ab30 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 g binding interf
2ab40 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 aces.** is a des
2ab50 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 tructor used to
2ab60 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 dispose of the B
2ab70 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 LOB or.** string
2ab80 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 after SQLite ha
2ab90 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 s finished with
2aba0 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 it. ^The destru
2abb0 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a ctor is called.*
2abc0 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 * to dispose of
2abd0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 the BLOB or stri
2abe0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 ng even if the c
2abf0 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 all to bind API
2ac00 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 fails..** ^If th
2ac10 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
2ac20 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 is.** the speci
2ac30 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 al value [SQLITE
2ac40 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 _STATIC], then S
2ac50 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 QLite assumes th
2ac60 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d at the.** inform
2ac70 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 ation is in stat
2ac80 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 ic, unmanaged sp
2ac90 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 ace and does not
2aca0 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 need to be free
2acb0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 d..** ^If the fi
2acc0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 fth argument has
2acd0 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 the value [SQLI
2ace0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 TE_TRANSIENT], t
2acf0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 hen.** SQLite ma
2ad00 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 kes its own priv
2ad10 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ate copy of the
2ad20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 data immediately
2ad30 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 , before.** the
2ad40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
2ad50 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2ad60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 ..**.** ^The six
2ad70 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 th argument to s
2ad80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2ad90 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 64() must be one
2ada0 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 of.** [SQLITE_U
2adb0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 TF8], [SQLITE_UT
2adc0 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 F16], [SQLITE_UT
2add0 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 F16BE], or [SQLI
2ade0 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 TE_UTF16LE].** t
2adf0 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e o specify the en
2ae00 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 coding of the te
2ae10 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 xt in the third
2ae20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a parameter. If.*
2ae30 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75 * the sixth argu
2ae40 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
2ae50 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 bind_text64() is
2ae60 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a not one of the.
2ae70 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 ** allowed value
2ae80 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f s shown above, o
2ae90 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e r if the text en
2aea0 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 coding is differ
2aeb0 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 ent.** from the
2aec0 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 encoding specifi
2aed0 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20 ed by the sixth
2aee0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 parameter, then
2aef0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 the behavior.**
2af00 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
2af10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2af20 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 _bind_zeroblob()
2af30 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 routine binds a
2af40 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 BLOB of length
2af50 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c N that.** is fil
2af60 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e led with zeroes.
2af70 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 ^A zeroblob us
2af80 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e es a fixed amoun
2af90 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 t of memory.** (
2afa0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 just an integer
2afb0 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 to hold its size
2afc0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 ) while it is be
2afd0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a ing processed..*
2afe0 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 * Zeroblobs are
2aff0 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 intended to serv
2b000 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 e as placeholder
2b010 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 s for BLOBs whos
2b020 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 e.** content is
2b030 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 later written us
2b040 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
2b050 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 blob_open | incr
2b060 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f emental BLOB I/O
2b070 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e ] routines..** ^
2b080 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 A negative value
2b090 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f for the zeroblo
2b0a0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a b results in a z
2b0b0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e ero-length BLOB.
2b0c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f .**.** ^If any o
2b0d0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 f the sqlite3_bi
2b0e0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
2b0f0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 are called with
2b100 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
2b110 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 * for the [prepa
2b120 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
2b130 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 r with a prepare
2b140 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 d statement for
2b150 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 which.** [sqlite
2b160 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 3_step()] has be
2b170 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 en called more r
2b180 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 ecently than [sq
2b190 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a lite3_reset()],.
2b1a0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c ** then the call
2b1b0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
2b1c0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 LITE_MISUSE]. I
2b1d0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 f any sqlite3_bi
2b1e0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 nd_().** routine
2b1f0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 is passed a [pr
2b200 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2b210 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 ] that has been
2b220 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a finalized, the.*
2b230 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 * result is unde
2b240 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
2b250 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a ly harmful..**.*
2b260 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 * ^Bindings are
2b270 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 not cleared by t
2b280 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 he [sqlite3_rese
2b290 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a t()] routine..**
2b2a0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 ^Unbound parame
2b2b0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 ters are interpr
2b2c0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a eted as NULL..**
2b2d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2b2e0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 _bind_* routines
2b2f0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
2b300 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f OK] on success o
2b310 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 r an.** [error c
2b320 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 ode] if anything
2b330 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 goes wrong..**
2b340 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d ^[SQLITE_TOOBIG]
2b350 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e might be return
2b360 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f ed if the size o
2b370 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c f a string or BL
2b380 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 OB.** exceeds li
2b390 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 mits imposed by
2b3a0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 [sqlite3_limit](
2b3b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 [SQLITE_LIMIT_LE
2b3c0 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 NGTH]) or.** [SQ
2b3d0 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d LITE_MAX_LENGTH]
2b3e0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 ..** ^[SQLITE_RA
2b3f0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 NGE] is returned
2b400 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
2b410 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 r.** index is ou
2b420 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 t of range. ^[S
2b430 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 QLITE_NOMEM] is
2b440 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c returned if mall
2b450 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a oc() fails..**.*
2b460 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
2b470 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2b480 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a ter_count()],.**
2b490 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
2b4a0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d arameter_name()]
2b4b0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 , and [sqlite3_b
2b4c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
2b4d0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 dex()]..*/.SQLIT
2b4e0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2b4f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2b500 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 _bind_blob(sqlit
2b510 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
2b520 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 onst void*, int
2b530 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a n, void(*)(void*
2b540 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 ));.SQLITE_API i
2b550 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
2b560 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 L sqlite3_bind_b
2b570 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 lob64(sqlite3_st
2b580 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
2b590 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 void*, sqlite3_u
2b5a0 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 int64,.
2b5b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
2b5c0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
2b5d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
2b5e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2b5f0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c lite3_bind_doubl
2b600 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2b610 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 int, double);.S
2b620 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2b630 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2b640 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 ite3_bind_int(sq
2b650 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2b660 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 , int);.SQLITE_A
2b670 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2b680 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 DCALL sqlite3_bi
2b690 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 nd_int64(sqlite3
2b6a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c _stmt*, int, sql
2b6b0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c ite3_int64);.SQL
2b6c0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
2b6d0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2b6e0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c e3_bind_null(sql
2b6f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 ite3_stmt*, int)
2b700 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2b710 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2b720 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2b730 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
2b740 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c int,const char*,
2b750 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 int,void(*)(void
2b760 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 *));.SQLITE_API
2b770 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2b780 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f LL sqlite3_bind_
2b790 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
2b7a0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
2b7b0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 void*, int, voi
2b7c0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 d(*)(void*));.SQ
2b7d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
2b7e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2b7f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 te3_bind_text64(
2b800 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2b810 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c nt, const char*,
2b820 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c sqlite3_uint64,
2b830 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
2b840 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a void(*
2b850 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e )(void*), unsign
2b860 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 ed char encoding
2b870 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2b880 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
2b890 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 sqlite3_bind_va
2b8a0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lue(sqlite3_stmt
2b8b0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 *, int, const sq
2b8c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
2b8d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2b8e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2b8f0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
2b900 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
2b910 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 53 , int, int n);.S
2b920 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2b930 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2b940 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
2b950 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d ob64(sqlite3_stm
2b960 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 t*, int, sqlite3
2b970 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a _uint64);../*.**
2b980 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
2b990 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 r Of SQL Paramet
2b9a0 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ers.** METHOD: s
2b9b0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2b9c0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
2b9d0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 can be used to f
2b9e0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ind the number o
2b9f0 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 f [SQL parameter
2ba00 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 s].** in a [prep
2ba10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
2ba20 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 SQL parameters
2ba30 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 are tokens of t
2ba40 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 he.** form "?",
2ba50 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 "?NNN", ":AAA",
2ba60 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 "$AAA", or "@AAA
2ba70 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a " that serve as.
2ba80 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 ** placeholders
2ba90 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 for values that
2baa0 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e are [sqlite3_bin
2bab0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a d_blob | bound].
2bac0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 ** to the parame
2bad0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 ters at a later
2bae0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 time..**.** ^(Th
2baf0 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 is routine actua
2bb00 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 lly returns the
2bb10 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 index of the lar
2bb20 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 gest (rightmost)
2bb30 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 .** parameter. F
2bb40 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 or all forms exc
2bb50 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 ept ?NNN, this w
2bb60 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 ill correspond t
2bb70 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 o the.** number
2bb80 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 of unique parame
2bb90 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 ters. If parame
2bba0 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e ters of the ?NNN
2bbb0 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a form are used,.
2bbc0 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 ** there may be
2bbd0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 gaps in the list
2bbe0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c .)^.**.** See al
2bbf0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
2bc00 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
2bc10 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ind()],.** [sqli
2bc20 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2bc30 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a er_name()], and.
2bc40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
2bc50 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
2bc60 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
2bc70 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2bc80 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 DCALL sqlite3_bi
2bc90 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
2bca0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a nt(sqlite3_stmt*
2bcb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2bcc0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f EF: Name Of A Ho
2bcd0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 st Parameter.**
2bce0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
2bcf0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 stmt.**.** ^The
2bd00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2bd10 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 ameter_name(P,N)
2bd20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2bd30 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f ns.** the name o
2bd40 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 f the N-th [SQL
2bd50 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 parameter] in th
2bd60 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2bd70 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 ement] P..** ^(S
2bd80 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 QL parameters of
2bd90 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 the form "?NNN"
2bda0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 or ":AAA" or "@
2bdb0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a AAA" or "$AAA".*
2bdc0 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 * have a name wh
2bdd0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e ich is the strin
2bde0 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 g "?NNN" or ":AA
2bdf0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 A" or "@AAA" or
2be00 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 "$AAA".** respec
2be10 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 tively..** In ot
2be20 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 her words, the i
2be30 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 nitial ":" or "$
2be40 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a " or "@" or "?".
2be50 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 ** is included a
2be60 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 s part of the na
2be70 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 me.)^.** ^Parame
2be80 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
2be90 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 "?" without a f
2bea0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 ollowing integer
2beb0 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a have no name.**
2bec0 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 and are referre
2bed0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 d to as "nameles
2bee0 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 s" or "anonymous
2bef0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a parameters"..**
2bf00 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 .** ^The first h
2bf10 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 ost parameter ha
2bf20 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c s an index of 1,
2bf30 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 not 0..**.** ^I
2bf40 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 f the value N is
2bf50 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 out of range or
2bf60 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 if the N-th par
2bf70 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d ameter is.** nam
2bf80 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c eless, then NULL
2bf90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e is returned. ^
2bfa0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
2bfb0 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 ing is.** always
2bfc0 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 in UTF-8 encodi
2bfd0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e ng even if the n
2bfe0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 amed parameter w
2bff0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 as.** originally
2c000 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 specified as UT
2c010 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 F-16 in [sqlite3
2c020 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 _prepare16()] or
2c030 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
2c040 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a pare16_v2()]..**
2c050 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
2c060 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2c070 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
2c080 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
2c090 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
2c0a0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 nt()], and.** [s
2c0b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2c0c0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
2c0d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
2c0e0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 nst char *SQLITE
2c0f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2c100 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2c110 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
2c120 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a t*, int);../*.**
2c130 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 CAPI3REF: Index
2c140 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 Of A Parameter
2c150 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d With A Given Nam
2c160 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c e.** METHOD: sql
2c170 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2c180 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 ^Return the inde
2c190 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 x of an SQL para
2c1a0 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 meter given its
2c1b0 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 name. ^The.** i
2c1c0 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 ndex value retur
2c1d0 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 ned is suitable
2c1e0 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 for use as the s
2c1f0 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 econd.** paramet
2c200 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 er to [sqlite3_b
2c210 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
2c220 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 _bind()]. ^A ze
2c230 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 ro.** is returne
2c240 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 d if no matching
2c250 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f parameter is fo
2c260 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d und. ^The param
2c270 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 eter.** name mus
2c280 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 t be given in UT
2c290 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 F-8 even if the
2c2a0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
2c2b0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 nt.** was prepar
2c2c0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 ed from UTF-16 t
2c2d0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ext using [sqlit
2c2e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
2c2f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c )]..**.** See al
2c300 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
2c310 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
2c320 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ind()],.** [sqli
2c330 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2c340 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 er_count()], and
2c350 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2c360 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
2c370 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
2c380 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2c390 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 DCALL sqlite3_bi
2c3a0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
2c3b0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ex(sqlite3_stmt*
2c3c0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
2c3d0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ame);../*.** CAP
2c3e0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c I3REF: Reset All
2c3f0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 Bindings On A P
2c400 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
2c410 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
2c420 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2c430 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 ^Contrary to the
2c440 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 intuition of ma
2c450 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ny, [sqlite3_res
2c460 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 et()] does not r
2c470 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c eset.** the [sql
2c480 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c ite3_bind_blob |
2c490 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 bindings] on a
2c4a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2c4b0 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 ent]..** ^Use th
2c4c0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 is routine to re
2c4d0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 set all host par
2c4e0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e ameters to NULL.
2c4f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2c500 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
2c510 4c 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f L sqlite3_clear_
2c520 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 bindings(sqlite3
2c530 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
2c540 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
2c550 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 Of Columns In A
2c560 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d Result Set.** M
2c570 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2c580 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 tmt.**.** ^Retur
2c590 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 n the number of
2c5a0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
2c5b0 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e esult set return
2c5c0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 ed by the.** [pr
2c5d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2c5e0 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ]. ^This routine
2c5f0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 returns 0 if pS
2c600 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a tmt is an SQL.**
2c610 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
2c620 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 does not return
2c630 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c data (for exampl
2c640 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a e an [UPDATE])..
2c650 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
2c660 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f [sqlite3_data_co
2c670 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 unt()].*/.SQLITE
2c680 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
2c690 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
2c6a0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c column_count(sql
2c6b0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
2c6c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2c6d0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 EF: Column Names
2c6e0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 In A Result Set
2c6f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
2c700 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
2c710 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
2c720 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 eturn the name a
2c730 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 ssigned to a par
2c740 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a ticular column.*
2c750 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 * in the result
2c760 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 set of a [SELECT
2c770 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 ] statement. ^T
2c780 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
2c790 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 n_name().** inte
2c7a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
2c7b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 pointer to a zer
2c7c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
2c7d0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 -8 string.** and
2c7e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2c7f0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 name16() returns
2c800 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
2c810 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
2c820 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 ** UTF-16 string
2c830 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 . ^The first pa
2c840 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
2c850 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2c860 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c nt].** that impl
2c870 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 ements the [SELE
2c880 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e CT] statement. ^
2c890 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
2c8a0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 eter is the.** c
2c8b0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e olumn number. ^
2c8c0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c The leftmost col
2c8d0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e umn is number 0.
2c8e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 .**.** ^The retu
2c8f0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e rned string poin
2c900 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 ter is valid unt
2c910 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 il either the [p
2c920 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2c930 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 t].** is destroy
2c940 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 ed by [sqlite3_f
2c950 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
2c960 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e til the statemen
2c970 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c t is automatical
2c980 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 ly.** reprepared
2c990 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 by the first ca
2c9a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
2c9b0 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 tep()] for a par
2c9c0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f ticular run.** o
2c9d0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 r until the next
2c9e0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 call to.** sqli
2c9f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
2ca00 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
2ca10 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 umn_name16() on
2ca20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e the same column.
2ca30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 .**.** ^If sqlit
2ca40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c e3_malloc() fail
2ca50 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f s during the pro
2ca60 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 cessing of eithe
2ca70 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f r routine.** (fo
2ca80 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 r example during
2ca90 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 a conversion fr
2caa0 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d om UTF-8 to UTF-
2cab0 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 16) then a.** NU
2cac0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 LL pointer is re
2cad0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 turned..**.** ^T
2cae0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 he name of a res
2caf0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 ult column is th
2cb00 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 e value of the "
2cb10 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a AS" clause for.*
2cb20 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 * that column, i
2cb30 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 f there is an AS
2cb40 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 clause. If the
2cb50 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 re is no AS clau
2cb60 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e se.** then the n
2cb70 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d ame of the colum
2cb80 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 n is unspecified
2cb90 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 and may change
2cba0 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 from.** one rele
2cbb0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f ase of SQLite to
2cbc0 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 the next..*/.SQ
2cbd0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
2cbe0 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 har *SQLITE_STDC
2cbf0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ALL sqlite3_colu
2cc00 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f mn_name(sqlite3_
2cc10 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 stmt*, int N);.S
2cc20 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2cc30 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 void *SQLITE_STD
2cc40 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
2cc50 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 umn_name16(sqlit
2cc60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 e3_stmt*, int N)
2cc70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2cc80 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 F: Source Of Dat
2cc90 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 a In A Query Res
2cca0 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ult.** METHOD: s
2ccb0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2ccc0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
2ccd0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e s provide a mean
2cce0 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 s to determine t
2ccf0 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 he database, tab
2cd00 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 le, and.** table
2cd10 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 column that is
2cd20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 the origin of a
2cd30 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c particular resul
2cd40 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b t column in.** [
2cd50 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
2cd60 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 t..** ^The name
2cd70 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
2cd80 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 or table or colu
2cd90 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e mn can be return
2cda0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 ed as.** either
2cdb0 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 a UTF-8 or UTF-1
2cdc0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 6 string. ^The
2cdd0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 _database_ routi
2cde0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 nes return.** th
2cdf0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c e database name,
2ce00 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 the _table_ rou
2ce10 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
2ce20 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 table name, and
2ce30 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 .** the origin_
2ce40 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
2ce50 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e the column name.
2ce60 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 .** ^The returne
2ce70 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 d string is vali
2ce80 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 d until the [pre
2ce90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2cea0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a is destroyed.**
2ceb0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
2cec0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 finalize()] or u
2ced0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 ntil the stateme
2cee0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 nt is automatica
2cef0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 lly.** reprepare
2cf00 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 d by the first c
2cf10 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2cf20 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 step()] for a pa
2cf30 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 rticular run.**
2cf40 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d or until the sam
2cf50 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 e information is
2cf60 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 requested.** ag
2cf70 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 ain in a differe
2cf80 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a nt encoding..**.
2cf90 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 ** ^The names re
2cfa0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f turned are the o
2cfb0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 riginal un-alias
2cfc0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a ed names of the.
2cfd0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 ** database, tab
2cfe0 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a le, and column..
2cff0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
2d000 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
2d010 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 se interfaces is
2d020 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2d030 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 tement]..** ^The
2d040 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 se functions ret
2d050 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 urn information
2d060 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 about the Nth re
2d070 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 sult column retu
2d080 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 rned by.** the s
2d090 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 tatement, where
2d0a0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 N is the second
2d0b0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e function argumen
2d0c0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d t..** ^The left-
2d0d0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 most column is c
2d0e0 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 olumn 0 for thes
2d0f0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a e routines..**.*
2d100 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f * ^If the Nth co
2d110 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 lumn returned by
2d120 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
2d130 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 s an expression
2d140 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 or.** subquery a
2d150 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 nd is not a colu
2d160 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 mn value, then a
2d170 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 ll of these func
2d180 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 tions return.**
2d190 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f NULL. ^These ro
2d1a0 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f utine might also
2d1b0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 return NULL if
2d1c0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
2d1d0 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 ion error.** occ
2d1e0 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 urs. ^Otherwise
2d1f0 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 , they return th
2d200 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 e name of the at
2d210 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c tached database,
2d220 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f table,.** or co
2d230 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 lumn that query
2d240 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 result column wa
2d250 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d s extracted from
2d260 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 ..**.** ^As with
2d270 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 all other SQLit
2d280 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 e APIs, those wh
2d290 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 ose names end wi
2d2a0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a th "16" return.*
2d2b0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 * UTF-16 encoded
2d2c0 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 strings and the
2d2d0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 other functions
2d2e0 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a return UTF-8..*
2d2f0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 *.** ^These APIs
2d300 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 are only availa
2d310 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 ble if the libra
2d320 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 ry was compiled
2d330 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c with the.** [SQL
2d340 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d ITE_ENABLE_COLUM
2d350 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 N_METADATA] C-pr
2d360 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f eprocessor symbo
2d370 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 l..**.** If two
2d380 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 or more threads
2d390 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 call one or more
2d3a0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
2d3b0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 es against the s
2d3c0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 ame.** prepared
2d3d0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f statement and co
2d3e0 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 lumn at the same
2d3f0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 time then the r
2d400 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e esults are.** un
2d410 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 defined..**.** I
2d420 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 f two or more th
2d430 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f reads call one o
2d440 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 r more.** [sqlit
2d450 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 e3_column_databa
2d460 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e se_name | column
2d470 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 metadata interf
2d480 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 aces].** for the
2d490 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 same [prepared
2d4a0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 statement] and r
2d4b0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 esult column.**
2d4c0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
2d4d0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
2d4e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
2d4f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 .*/.SQLITE_API c
2d500 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 onst char *SQLIT
2d510 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2d520 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
2d530 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 e_name(sqlite3_s
2d540 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 tmt*,int);.SQLIT
2d550 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
2d560 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
2d570 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2d580 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 database_name16(
2d590 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2d5a0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 t);.SQLITE_API c
2d5b0 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 onst char *SQLIT
2d5c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2d5d0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 3_column_table_n
2d5e0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
2d5f0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 *,int);.SQLITE_A
2d600 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 PI const void *S
2d610 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2d620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 lite3_column_tab
2d630 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 le_name16(sqlite
2d640 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 3_stmt*,int);.SQ
2d650 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
2d660 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 har *SQLITE_STDC
2d670 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ALL sqlite3_colu
2d680 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 mn_origin_name(s
2d690 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2d6a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
2d6b0 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 nst void *SQLITE
2d6c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2d6d0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e _column_origin_n
2d6e0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
2d6f0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a mt*,int);../*.**
2d700 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 CAPI3REF: Decla
2d710 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 red Datatype Of
2d720 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a A Query Result.*
2d730 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
2d740 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 3_stmt.**.** ^(T
2d750 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
2d760 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 er is a [prepare
2d770 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
2d780 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 If this stateme
2d790 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d nt is a [SELECT]
2d7a0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
2d7b0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
2d7c0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 the.** returned
2d7d0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 result set of t
2d7e0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 hat [SELECT] is
2d7f0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 a table column (
2d800 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 not an.** expres
2d810 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
2d820 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 ) then the decla
2d830 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 red type of the
2d840 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 table.** column
2d850 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 is returned.)^
2d860 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 ^If the Nth colu
2d870 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 mn of the result
2d880 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 set is an.** ex
2d890 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 pression or subq
2d8a0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c uery, then a NUL
2d8b0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
2d8c0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 urned..** ^The r
2d8d0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
2d8e0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 s always UTF-8 e
2d8f0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ncoded..**.** ^(
2d900 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 For example, giv
2d910 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
2d920 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 schema:.**.** CR
2d930 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 EATE TABLE t1(c1
2d940 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a VARIANT);.**.**
2d950 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 and the followi
2d960 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 ng statement to
2d970 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a be compiled:.**.
2d980 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 ** SELECT c1 + 1
2d990 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a , c1 FROM t1;.**
2d9a0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
2d9b0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 would return th
2d9c0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e e string "VARIAN
2d9d0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e T" for the secon
2d9e0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 d result.** colu
2d9f0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 mn (i==1), and a
2da00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f NULL pointer fo
2da10 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 r the first resu
2da20 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 lt column (i==0)
2da30 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 .)^.**.** ^SQLit
2da40 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 e uses dynamic r
2da50 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 un-time typing.
2da60 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 ^So just becaus
2da70 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 e a column.** is
2da80 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e declared to con
2da90 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 tain a particula
2daa0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 r type does not
2dab0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a mean that the.**
2dac0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 data stored in
2dad0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f that column is o
2dae0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 f the declared t
2daf0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a ype. SQLite is.
2db00 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 ** strongly type
2db10 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e d, but the typin
2db20 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 g is dynamic not
2db30 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a static. ^Type.
2db40 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 ** is associated
2db50 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c with individual
2db60 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 values, not wit
2db70 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 h the containers
2db80 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 .** used to hold
2db90 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a those values..*
2dba0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
2dbb0 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f st char *SQLITE_
2dbc0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
2dbd0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 column_decltype(
2dbe0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2dbf0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 t);.SQLITE_API c
2dc00 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 onst void *SQLIT
2dc10 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2dc20 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
2dc30 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
2dc40 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 *,int);../*.** C
2dc50 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 API3REF: Evaluat
2dc60 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 e An SQL Stateme
2dc70 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 nt.** METHOD: sq
2dc80 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2dc90 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 After a [prepar
2dca0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 ed statement] ha
2dcb0 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 s been prepared
2dcc0 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 using either.**
2dcd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2dce0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
2dcf0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
2dd00 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 )] or one of the
2dd10 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 legacy.** inter
2dd20 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 faces [sqlite3_p
2dd30 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 repare()] or [sq
2dd40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
2dd50 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f )], this functio
2dd60 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c n.** must be cal
2dd70 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 led one or more
2dd80 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 times to evaluat
2dd90 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e e the statement.
2dda0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 .**.** The detai
2ddb0 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 ls of the behavi
2ddc0 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 or of the sqlite
2ddd0 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 3_step() interfa
2dde0 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 ce depend.** on
2ddf0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 whether the stat
2de00 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 ement was prepar
2de10 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 ed using the new
2de20 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 er "v2" interfac
2de30 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 e.** [sqlite3_pr
2de40 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
2de50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2de60 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 16_v2()] or the
2de70 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 older legacy.**
2de80 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 interface [sqlit
2de90 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e e3_prepare()] an
2dea0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
2deb0 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 re16()]. The us
2dec0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 e of the.** new
2ded0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 "v2" interface i
2dee0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f s recommended fo
2def0 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f r new applicatio
2df00 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 ns but the legac
2df10 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 y.** interface w
2df20 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 ill continue to
2df30 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a be supported..**
2df40 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 .** ^In the lega
2df50 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 cy interface, th
2df60 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 e return value w
2df70 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 ill be either [S
2df80 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 QLITE_BUSY],.**
2df90 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b [SQLITE_DONE], [
2dfa0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 SQLITE_ROW], [SQ
2dfb0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 LITE_ERROR], or
2dfc0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e [SQLITE_MISUSE].
2dfd0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 .** ^With the "v
2dfe0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 2" interface, an
2dff0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b y of the other [
2e000 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 result codes] or
2e010 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
2e020 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 sult codes] migh
2e030 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 t be returned as
2e040 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 well..**.** ^[S
2e050 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e QLITE_BUSY] mean
2e060 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 s that the datab
2e070 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 ase engine was u
2e080 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 nable to acquire
2e090 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
2e0a0 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 locks it needs
2e0b0 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 to do its job.
2e0c0 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e ^If the statemen
2e0d0 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a t is a [COMMIT].
2e0e0 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 ** or occurs out
2e0f0 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 side of an expli
2e100 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c cit transaction,
2e110 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 then you can re
2e120 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 try the.** state
2e130 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 ment. If the st
2e140 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 atement is not a
2e150 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 [COMMIT] and oc
2e160 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a curs within an.*
2e170 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 * explicit trans
2e180 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 action then you
2e190 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 should rollback
2e1a0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 the transaction
2e1b0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e before.** contin
2e1c0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 uing..**.** ^[SQ
2e1d0 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 LITE_DONE] means
2e1e0 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d that the statem
2e1f0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 ent has finished
2e200 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 executing.** su
2e210 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c ccessfully. sql
2e220 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 ite3_step() shou
2e230 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 ld not be called
2e240 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 again on this v
2e250 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e irtual.** machin
2e260 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 e without first
2e270 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
2e280 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 _reset()] to res
2e290 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a et the virtual.*
2e2a0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 * machine back t
2e2b0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 o its initial st
2e2c0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ate..**.** ^If t
2e2d0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
2e2e0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 being executed
2e2f0 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 returns any data
2e300 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 , then [SQLITE_R
2e310 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e OW].** is return
2e320 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e ed each time a n
2e330 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 ew row of data i
2e340 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 s ready for proc
2e350 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a essing by the.**
2e360 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c caller. The val
2e370 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 ues may be acces
2e380 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 sed using the [c
2e390 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e olumn access fun
2e3a0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 ctions]..** sqli
2e3b0 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 te3_step() is ca
2e3c0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 lled again to re
2e3d0 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 trieve the next
2e3e0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a row of data..**.
2e3f0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f ** ^[SQLITE_ERRO
2e400 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 R] means that a
2e410 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 run-time error (
2e420 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 such as a constr
2e430 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f aint.** violatio
2e440 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e n) has occurred.
2e450 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 sqlite3_step()
2e460 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 should not be c
2e470 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a alled again on.*
2e480 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 * the VM. More i
2e490 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 nformation may b
2e4a0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 e found by calli
2e4b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ng [sqlite3_errm
2e4c0 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 sg()]..** ^With
2e4d0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 the legacy inter
2e4e0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 face, a more spe
2e4f0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 cific error code
2e500 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a (for example,.*
2e510 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 * [SQLITE_INTERR
2e520 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 UPT], [SQLITE_SC
2e530 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 HEMA], [SQLITE_C
2e540 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 ORRUPT], and so
2e550 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 forth).** can be
2e560 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c obtained by cal
2e570 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 ling [sqlite3_re
2e580 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a set()] on the.**
2e590 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2e5a0 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 ment]. ^In the
2e5b0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a "v2" interface,.
2e5c0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 ** the more spec
2e5d0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 ific error code
2e5e0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 is returned dire
2e5f0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f ctly by sqlite3_
2e600 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 step()..**.** [S
2e610 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 QLITE_MISUSE] me
2e620 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 ans that the thi
2e630 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 s routine was ca
2e640 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 lled inappropria
2e650 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 tely..** Perhaps
2e660 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f it was called o
2e670 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
2e680 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 atement] that ha
2e690 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 s.** already bee
2e6a0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c n [sqlite3_final
2e6b0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d ize | finalized]
2e6c0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 or on one that
2e6d0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c had.** previousl
2e6e0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 y returned [SQLI
2e6f0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 TE_ERROR] or [SQ
2e700 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 LITE_DONE]. Or
2e710 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 it could.** be t
2e720 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 he case that the
2e730 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
2e740 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 onnection is bei
2e750 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f ng used by two o
2e760 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 r.** more thread
2e770 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f s at the same mo
2e780 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a ment in time..**
2e790 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 .** For all vers
2e7a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 ions of SQLite u
2e7b0 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 p to and includi
2e7c0 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 ng 3.6.23.1, a c
2e7d0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
2e7e0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 e3_reset()] was
2e7f0 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73 required after s
2e800 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 qlite3_step() re
2e810 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a turned anything.
2e820 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 ** other than [S
2e830 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 QLITE_ROW] befor
2e840 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 e any subsequent
2e850 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a invocation of.*
2e860 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
2e870 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 . Failure to re
2e880 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 set the prepared
2e890 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 statement using
2e8a0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 .** [sqlite3_re
2e8b0 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 set()] would res
2e8c0 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 ult in an [SQLIT
2e8d0 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e E_MISUSE] return
2e8e0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 from.** sqlite3
2e8f0 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 _step(). But af
2e900 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e ter version 3.6.
2e910 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 23.1, sqlite3_st
2e920 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 ep() began.** ca
2e930 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
2e940 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 eset()] automati
2e950 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 cally in this ci
2e960 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 rcumstance rathe
2e970 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e r.** than return
2e980 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 ing [SQLITE_MISU
2e990 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f SE]. This is no
2e9a0 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 t considered a c
2e9b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 ompatibility.**
2e9c0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e break because an
2e9d0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 y application th
2e9e0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 at ever receives
2e9f0 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 an SQLITE_MISUS
2ea00 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 E error.** is br
2ea10 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 oken by definiti
2ea20 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 on. The [SQLITE
2ea30 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d _OMIT_AUTORESET]
2ea40 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
2ea50 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 tion.** can be u
2ea60 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 sed to restore t
2ea70 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 he legacy behavi
2ea80 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f or..**.** <b>Goo
2ea90 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 fy Interface Ale
2eaa0 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c rt:</b> In the l
2eab0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c egacy interface,
2eac0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 the sqlite3_ste
2ead0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 p().** API alway
2eae0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 s returns a gene
2eaf0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 ric error code,
2eb00 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 [SQLITE_ERROR],
2eb10 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a following any.**
2eb20 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 error other tha
2eb30 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 n [SQLITE_BUSY]
2eb40 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 and [SQLITE_MISU
2eb50 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 SE]. You must c
2eb60 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f all.** [sqlite3_
2eb70 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c reset()] or [sql
2eb80 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
2eb90 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e in order to fin
2eba0 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 d one of the.**
2ebb0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 specific [error
2ebc0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 codes] that bett
2ebd0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 er describes the
2ebe0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 error..** We ad
2ebf0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 mit that this is
2ec00 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e a goofy design.
2ec10 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 The problem ha
2ec20 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 s been fixed.**
2ec30 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e with the "v2" in
2ec40 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 terface. If you
2ec50 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 prepare all of
2ec60 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 your SQL stateme
2ec70 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 nts.** using eit
2ec80 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 her [sqlite3_pre
2ec90 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 pare_v2()] or [s
2eca0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2ecb0 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a _v2()] instead.*
2ecc0 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 * of the legacy
2ecd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2ece0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2ecf0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e _prepare16()] in
2ed00 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 terfaces,.** the
2ed10 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 n the more speci
2ed20 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 fic [error codes
2ed30 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 ] are returned d
2ed40 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 irectly.** by sq
2ed50 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 lite3_step(). T
2ed60 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 he use of the "v
2ed70 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 2" interface is
2ed80 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a recommended..*/.
2ed90 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
2eda0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2edb0 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 lite3_step(sqlit
2edc0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
2edd0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
2ede0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
2edf0 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a a result set.**
2ee00 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2ee10 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _stmt.**.** ^The
2ee20 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
2ee30 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 unt(P) interface
2ee40 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
2ee50 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
2ee60 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 n the.** current
2ee70 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 row of the resu
2ee80 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 lt set of [prepa
2ee90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 red statement] P
2eea0 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 ..** ^If prepare
2eeb0 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f d statement P do
2eec0 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 es not have resu
2eed0 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 lts ready to ret
2eee0 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c urn.** (via call
2eef0 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 s to the [sqlite
2ef00 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 3_column_int | s
2ef10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 qlite3_column_*(
2ef20 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 )] of.** interfa
2ef30 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 ces) then sqlite
2ef40 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 3_data_count(P)
2ef50 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 returns 0..** ^T
2ef60 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
2ef70 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 count(P) routine
2ef80 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 also returns 0
2ef90 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 if P is a NULL p
2efa0 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 ointer..** ^The
2efb0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
2efc0 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 nt(P) routine re
2efd0 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 turns 0 if the p
2efe0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a revious call to.
2eff0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
2f000 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 ](P) returned [S
2f010 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 QLITE_DONE]. ^T
2f020 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
2f030 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c count(P).** will
2f040 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f return non-zero
2f050 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c if previous cal
2f060 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
2f070 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a ep](P) returned.
2f080 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c ** [SQLITE_ROW],
2f090 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 except in the c
2f0a0 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 ase of the [PRAG
2f0b0 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 MA incremental_v
2f0c0 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 acuum].** where
2f0d0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e it always return
2f0e0 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 s zero since eac
2f0f0 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d h step of that m
2f100 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 ulti-step.** pra
2f110 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f gma returns 0 co
2f120 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a lumns of data..*
2f130 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2f140 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
2f150 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 ount()].*/.SQLIT
2f160 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2f170 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2f180 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 _data_count(sqli
2f190 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2f1a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2f1b0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 F: Fundamental D
2f1c0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 atatypes.** KEYW
2f1d0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 ORDS: SQLITE_TEX
2f1e0 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 T.**.** ^(Every
2f1f0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 value in SQLite
2f200 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 has one of five
2f210 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 fundamental data
2f220 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c types:.**.** <ul
2f230 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 >.** <li> 64-bit
2f240 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
2f250 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 ** <li> 64-bit I
2f260 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 EEE floating poi
2f270 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 nt number.** <li
2f280 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e > string.** <li>
2f290 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 BLOB.** <li> NU
2f2a0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a LL.** </ul>)^.**
2f2b0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
2f2c0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f nts are codes fo
2f2d0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 r each of those
2f2e0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 types..**.** Not
2f2f0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 e that the SQLIT
2f300 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 E_TEXT constant
2f310 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e was also used in
2f320 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
2f330 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 2.** for a compl
2f340 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 etely different
2f350 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 meaning. Softwa
2f360 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 re that links ag
2f370 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 ainst both.** SQ
2f380 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 Lite version 2 a
2f390 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f nd SQLite versio
2f3a0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 n 3 should use S
2f3b0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 QLITE3_TEXT, not
2f3c0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e .** SQLITE_TEXT.
2f3d0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
2f3e0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 TE_INTEGER 1.#d
2f3f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f efine SQLITE_FLO
2f400 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 AT 2.#define
2f410 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 SQLITE_BLOB
2f420 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
2f430 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 _NULL 5.#ifd
2f440 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 ef SQLITE_TEXT.#
2f450 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 undef SQLITE_TE
2f460 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e XT.#else.# defin
2f470 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 e SQLITE_TEXT
2f480 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 3.#endif.#defi
2f490 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 ne SQLITE3_TEXT
2f4a0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 3../*.** CAP
2f4b0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 I3REF: Result Va
2f4c0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 lues From A Quer
2f4d0 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b y.** KEYWORDS: {
2f4e0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
2f4f0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 nctions}.** METH
2f500 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2f510 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
2f520 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e utines return in
2f530 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
2f540 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 a single column
2f550 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a of the current.*
2f560 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 * result row of
2f570 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 a query. ^In ev
2f580 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 ery case the fir
2f590 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 st argument is a
2f5a0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 pointer.** to t
2f5b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2f5c0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 tement] that is
2f5d0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 being evaluated
2f5e0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 (the [sqlite3_st
2f5f0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 mt*].** that was
2f600 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b returned from [
2f610 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2f620 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 v2()] or one of
2f630 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a its variants).**
2f640 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
2f650 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
2f660 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c index of the col
2f670 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e umn for which in
2f680 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f formation.** sho
2f690 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e uld be returned.
2f6a0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 ^The leftmost c
2f6b0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 olumn of the res
2f6c0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 ult set has the
2f6d0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 index 0..** ^The
2f6e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
2f6f0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
2f700 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e can be determin
2f710 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c ed using.** [sql
2f720 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e ite3_column_coun
2f730 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 t()]..**.** If t
2f740 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
2f750 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e does not curren
2f760 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 tly point to a v
2f770 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 alid row, or if
2f780 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e the.** column in
2f790 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 dex is out of ra
2f7a0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 nge, the result
2f7b0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
2f7c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
2f7d0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c may only be call
2f7e0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 ed when the most
2f7f0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a recent call to.
2f800 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
2f810 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 ()] has returned
2f820 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e [SQLITE_ROW] an
2f830 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 d neither.** [sq
2f840 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e lite3_reset()] n
2f850 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
2f860 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 lize()] have bee
2f870 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 n called subsequ
2f880 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 ently..** If any
2f890 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
2f8a0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 es are called af
2f8b0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ter [sqlite3_res
2f8c0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c et()] or.** [sql
2f8d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
2f8e0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 or after [sqlit
2f8f0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 e3_step()] has r
2f900 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 eturned.** somet
2f910 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 hing other than
2f920 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 [SQLITE_ROW], th
2f930 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
2f940 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b defined..** If [
2f950 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2f960 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
2f970 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 t()] or [sqlite3
2f980 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 _finalize()].**
2f990 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 are called from
2f9a0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 a different thre
2f9b0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 ad while any of
2f9c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a these routines.*
2f9d0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 * are pending, t
2f9e0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
2f9f0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
2fa00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2fa10 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 3_column_type()
2fa20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
2fa30 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 the.** [SQLITE_I
2fa40 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 NTEGER | datatyp
2fa50 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 e code] for the
2fa60 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 initial data typ
2fa70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 e.** of the resu
2fa80 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 lt column. ^The
2fa90 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 returned value
2faa0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 is one of [SQLIT
2fab0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b E_INTEGER],.** [
2fac0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b SQLITE_FLOAT], [
2fad0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 SQLITE_TEXT], [S
2fae0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 QLITE_BLOB], or
2faf0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 [SQLITE_NULL].
2fb00 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 The value.** ret
2fb10 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
2fb20 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 _column_type() i
2fb30 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 s only meaningfu
2fb40 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 l if no type.**
2fb50 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 conversions have
2fb60 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 occurred as des
2fb70 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 cribed below. A
2fb80 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 fter a type conv
2fb90 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 ersion,.** the v
2fba0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
2fbb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2fbc0 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 type() is undefi
2fbd0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 ned. Future.**
2fbe0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
2fbf0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 te may change th
2fc00 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 e behavior of sq
2fc10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
2fc20 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 e().** following
2fc30 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 a type conversi
2fc40 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 on..**.** ^If th
2fc50 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c e result is a BL
2fc60 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 OB or UTF-8 stri
2fc70 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 ng then the sqli
2fc80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2fc90 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 ().** routine re
2fca0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
2fcb0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 of bytes in tha
2fcc0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 t BLOB or string
2fcd0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
2fce0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 ult is a UTF-16
2fcf0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c string, then sql
2fd00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2fd10 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 s() converts.**
2fd20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 the string to UT
2fd30 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 F-8 and then ret
2fd40 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
2fd50 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 of bytes..** ^If
2fd60 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
2fd70 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 numeric value t
2fd80 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
2fd90 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a mn_bytes() uses.
2fda0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 ** [sqlite3_snpr
2fdb0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 intf()] to conve
2fdc0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f rt that value to
2fdd0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 a UTF-8 string
2fde0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 and returns.** t
2fdf0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
2fe00 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e es in that strin
2fe10 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 g..** ^If the re
2fe20 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 sult is NULL, th
2fe30 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2fe40 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e n_bytes() return
2fe50 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 s zero..**.** ^I
2fe60 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
2fe70 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 a BLOB or UTF-16
2fe80 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 string then the
2fe90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2fea0 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 bytes16().** rou
2feb0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
2fec0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2fed0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 in that BLOB or
2fee0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
2fef0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2ff00 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 UTF-8 string, th
2ff10 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2ff20 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 n_bytes16() conv
2ff30 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 erts.** the stri
2ff40 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 ng to UTF-16 and
2ff50 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 then returns th
2ff60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
2ff70 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 s..** ^If the re
2ff80 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 sult is a numeri
2ff90 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c c value then sql
2ffa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2ffb0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 s16() uses.** [s
2ffc0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
2ffd0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 )] to convert th
2ffe0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 at value to a UT
2fff0 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 F-16 string and
30000 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
30010 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
30020 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a n that string..*
30030 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
30040 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 is NULL, then s
30050 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
30060 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 tes16() returns
30070 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 zero..**.** ^The
30080 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 values returned
30090 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c by [sqlite3_col
300a0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 umn_bytes()] and
300b0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f .** [sqlite3_co
300c0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 lumn_bytes16()]
300d0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 do not include t
300e0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 he zero terminat
300f0 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a ors at the end.*
30100 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e * of the string.
30110 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 ^For clarity:
30120 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 the values retur
30130 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ned by.** [sqlit
30140 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
30150 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
30160 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
30170 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 ] are the number
30180 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 of.** bytes in
30190 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 the string, not
301a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
301b0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 aracters..**.**
301c0 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 ^Strings returne
301d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
301e0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 umn_text() and s
301f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
30200 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 xt16(),.** even
30210 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 empty strings, a
30220 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 re always zero-t
30230 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 erminated. ^The
30240 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 return.** value
30250 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f from sqlite3_co
30260 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 lumn_blob() for
30270 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c a zero-length BL
30280 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 OB is a NULL poi
30290 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 nter..**.** <b>W
302a0 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 arning:</b> ^The
302b0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
302c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c by [sqlite3_col
302d0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 umn_value()] is
302e0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 an.** [unprotect
302f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
30300 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 ] object. In a
30310 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e multithreaded en
30320 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e vironment,.** an
30330 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c unprotected sql
30340 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
30350 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 t may only be us
30360 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a ed safely with.*
30370 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
30380 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 value()] and [sq
30390 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
303a0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 ue()]..** If the
303b0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
303c0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
303d0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
303e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
303f0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
30400 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 sed in any other
30410 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 way, including
30420 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 calls.** to rout
30430 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 ines like [sqlit
30440 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c e3_value_int()],
30450 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
30460 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b text()],.** or [
30470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
30480 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 tes()], the beha
30490 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 vior is not thre
304a0 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 adsafe..**.** Th
304b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 ese routines att
304c0 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 empt to convert
304d0 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 the value where
304e0 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 appropriate. ^F
304f0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 or.** example, i
30500 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 f the internal r
30510 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 epresentation is
30520 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 FLOAT and a tex
30530 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 t result.** is r
30540 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 equested, [sqlit
30550 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 e3_snprintf()] i
30560 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c s used internall
30570 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 y to perform the
30580 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 .** conversion a
30590 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e utomatically. ^
305a0 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 (The following t
305b0 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 able details the
305c0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 conversions.**
305d0 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 that are applied
305e0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
305f0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 ote>.** <table b
30600 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 order="1">.** <t
30610 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c r><th> Internal<
30620 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 br>Type <th> Req
30630 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c uested<br>Type <
30640 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a th> Conversion.
30650 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 **.** <tr><td>
30660 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 NULL <td> INT
30670 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 EGER <td> Resu
30680 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c lt is 0.** <tr><
30690 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
306a0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
306b0 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a Result is 0.0.*
306c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
306d0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 <td> TEXT
306e0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
306f0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
30700 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
30710 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f LL <td> BLO
30720 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 B <td> Result
30730 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
30740 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 er.** <tr><td> I
30750 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c NTEGER <td> FL
30760 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 OAT <td> Conv
30770 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 ert from integer
30780 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 to float.** <tr
30790 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
307a0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 td> TEXT <t
307b0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 d> ASCII renderi
307c0 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 ng of the intege
307d0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e r.** <tr><td> IN
307e0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c TEGER <td> BL
307f0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 OB <td> Same
30800 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 as INTEGER->TEXT
30810 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
30820 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 OAT <td> INTEG
30830 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d ER <td> [CAST]
30840 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c to INTEGER.** <
30850 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
30860 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
30870 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 <td> ASCII rende
30880 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 ring of the floa
30890 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 t.** <tr><td> F
308a0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c LOAT <td> BL
308b0 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 OB <td> [CAST
308c0 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 ] to BLOB.** <tr
308d0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
308e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
308f0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 d> [CAST] to INT
30900 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e EGER.** <tr><td>
30910 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 TEXT <td>
30920 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 FLOAT <td> [C
30930 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 AST] to REAL.**
30940 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 <tr><td> TEXT
30950 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
30960 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a <td> No change.
30970 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f ** <tr><td> BLO
30980 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 B <td> INTEGE
30990 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 R <td> [CAST]
309a0 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 to INTEGER.** <t
309b0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
309c0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
309d0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 td> [CAST] to RE
309e0 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 AL.** <tr><td>
309f0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 BLOB <td> T
30a00 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 EXT <td> Add
30a10 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f a zero terminato
30a20 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c r if needed.** <
30a30 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f /table>.** </blo
30a40 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a ckquote>)^.**.**
30a50 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 Note that when
30a60 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 type conversions
30a70 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 occur, pointers
30a80 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 returned by pri
30a90 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 or.** calls to s
30aa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
30ab0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f ob(), sqlite3_co
30ac0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 lumn_text(), and
30ad0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 /or.** sqlite3_c
30ae0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d olumn_text16() m
30af0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 ay be invalidate
30b00 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 d..** Type conve
30b10 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 rsions and point
30b20 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 er invalidations
30b30 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 might occur.**
30b40 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 in the following
30b50 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 cases:.**.** <u
30b60 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 l>.** <li> The i
30b70 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
30b80 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c s a BLOB and sql
30b90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
30ba0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
30bb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
30bc0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e t16() is called.
30bd0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 A zero-termina
30be0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 tor might.**
30bf0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 need to be add
30c00 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 ed to the string
30c10 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 .</li>.** <li> T
30c20 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
30c30 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 nt is UTF-8 text
30c40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
30c50 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 umn_bytes16() or
30c60 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
30c70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
30c80 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 is called. The
30c90 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 content must be
30ca0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 converted.**
30cb0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c to UTF-16.</l
30cc0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 i>.** <li> The i
30cd0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
30ce0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e s UTF-16 text an
30cf0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
30d00 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 _bytes() or.**
30d10 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
30d20 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c mn_text() is cal
30d30 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
30d40 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
30d50 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 ted.** to U
30d60 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f TF-8.</li>.** </
30d70 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 ul>.**.** ^Conve
30d80 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 rsions between U
30d90 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d TF-16be and UTF-
30da0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 16le are always
30db0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e done in place an
30dc0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 d do.** not inva
30dd0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 lidate a prior p
30de0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f ointer, though o
30df0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e f course the con
30e00 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 tent of the buff
30e10 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 er.** that the p
30e20 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 rior pointer ref
30e30 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 erences will hav
30e40 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e e been modified.
30e50 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a Other kinds.**
30e60 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 of conversion a
30e70 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 re done in place
30e80 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 when it is poss
30e90 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 ible, but someti
30ea0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 mes they.** are
30eb0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 not possible and
30ec0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 in those cases
30ed0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 prior pointers a
30ee0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a re invalidated..
30ef0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 **.** The safest
30f00 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e policy is to in
30f10 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 voke these routi
30f20 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 nes.** in one of
30f30 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 the following w
30f40 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ays:.**.** <ul>.
30f50 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f ** <li>sqlite3_
30f60 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f column_text() fo
30f70 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
30f80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
30f90 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 </li>.** <li>sq
30fa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
30fb0 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 b() followed by
30fc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
30fd0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 ytes()</li>.**
30fe0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
30ff0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c mn_text16() foll
31000 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f owed by sqlite3_
31010 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
31020 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a </li>.** </ul>.*
31030 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f *.** In other wo
31040 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 rds, you should
31050 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c call sqlite3_col
31060 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 umn_text(),.** s
31070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
31080 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 ob(), or sqlite3
31090 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
310a0 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 first to force
310b0 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e the result.** in
310c0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 to the desired f
310d0 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f ormat, then invo
310e0 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ke sqlite3_colum
310f0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 n_bytes() or.**
31100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
31110 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 ytes16() to find
31120 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
31130 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 result. Do not
31140 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f mix calls.** to
31150 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
31160 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 text() or sqlite
31170 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 3_column_blob()
31180 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a with calls to.**
31190 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
311a0 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 bytes16(), and d
311b0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 o not mix calls
311c0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
311d0 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 n_text16().** wi
311e0 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 th calls to sqli
311f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
31200 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 ()..**.** ^The p
31210 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
31220 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c are valid until
31230 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 a type conversi
31240 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 on occurs as.**
31250 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c described above,
31260 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 or until [sqlit
31270 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 e3_step()] or [s
31280 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
31290 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 or.** [sqlite3_f
312a0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 inalize()] is ca
312b0 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f lled. ^The memo
312c0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f ry space used to
312d0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a hold strings.**
312e0 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 and BLOBs is fr
312f0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c eed automaticall
31300 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f y. Do <em>not</
31310 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 em> pass the poi
31320 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a nters returned.*
31330 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
31340 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 column_blob()],
31350 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
31360 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e text()], etc. in
31370 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 to.** [sqlite3_f
31380 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ree()]..**.** ^(
31390 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f If a memory allo
313a0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 cation error occ
313b0 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 urs during the e
313c0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 valuation of any
313d0 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 .** of these rou
313e0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 tines, a default
313f0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e value is return
31400 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 ed. The default
31410 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 value.** is eit
31420 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 her the integer
31430 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 0, the floating
31440 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 point number 0.0
31450 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 , or a NULL.** p
31460 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 ointer. Subsequ
31470 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
31480 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
31490 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 will return.**
314a0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 [SQLITE_NOMEM].)
314b0 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ^.*/.SQLITE_API
314c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 const void *SQLI
314d0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
314e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 e3_column_blob(s
314f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
31500 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
31510 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
31520 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
31530 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 olumn_bytes(sqli
31540 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
31550 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
31560 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
31570 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ALL sqlite3_colu
31580 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 mn_bytes16(sqlit
31590 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
315a0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
315b0 64 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 double SQLITE_ST
315c0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f DCALL sqlite3_co
315d0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 lumn_double(sqli
315e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
315f0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
31600 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
31610 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ALL sqlite3_colu
31620 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 mn_int(sqlite3_s
31630 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
31640 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
31650 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 te3_int64 SQLITE
31660 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
31670 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 _column_int64(sq
31680 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
31690 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
316a0 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 PI const unsigne
316b0 64 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 d char *SQLITE_S
316c0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
316d0 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 olumn_text(sqlit
316e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
316f0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
31700 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 const void *SQLI
31710 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
31720 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
31730 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
31740 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
31750 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
31760 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
31770 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c _column_type(sql
31780 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
31790 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
317a0 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 I sqlite3_value
317b0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
317c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
317d0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d alue(sqlite3_stm
317e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a t*, int iCol);..
317f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
31800 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 Destroy A Prepar
31810 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a ed Statement Obj
31820 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f ect.** DESTRUCTO
31830 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a R: sqlite3_stmt.
31840 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
31850 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 e3_finalize() fu
31860 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 nction is called
31870 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 to delete a [pr
31880 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
31890 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f ]..** ^If the mo
318a0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 st recent evalua
318b0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 tion of the stat
318c0 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 ement encountere
318d0 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f d no errors.** o
318e0 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 r if the stateme
318f0 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e nt is never been
31900 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e evaluated, then
31910 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
31920 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 e() returns.** S
31930 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 QLITE_OK. ^If t
31940 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 he most recent e
31950 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 valuation of sta
31960 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c tement S failed,
31970 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 then.** sqlite3
31980 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 _finalize(S) ret
31990 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 urns the appropr
319a0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 iate [error code
319b0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
319c0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a d error code]..*
319d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
319e0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 3_finalize(S) ro
319f0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c utine can be cal
31a00 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 led at any point
31a10 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c during.** the l
31a20 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 ife cycle of [pr
31a30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
31a40 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 ] S:.** before s
31a50 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 tatement S is ev
31a60 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 er evaluated, af
31a70 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f ter.** one or mo
31a80 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c re calls to [sql
31a90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f ite3_reset()], o
31aa0 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c r after any call
31ab0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f .** to [sqlite3_
31ac0 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 step()] regardle
31ad0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
31ae0 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 not the stateme
31af0 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 nt has.** comple
31b00 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a ted execution..*
31b10 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 *.** ^Invoking s
31b20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
31b30 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ) on a NULL poin
31b40 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 ter is a harmles
31b50 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 s no-op..**.** T
31b60 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
31b70 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 ust finalize eve
31b80 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ry [prepared sta
31b90 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 tement] in order
31ba0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 to avoid.** res
31bb0 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 ource leaks. It
31bc0 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 is a grievous e
31bd0 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 rror for the app
31be0 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 lication to try
31bf0 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 to use.** a prep
31c00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 ared statement a
31c10 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e fter it has been
31c20 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 finalized. Any
31c30 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 use of a prepar
31c40 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 ed.** statement
31c50 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 after it has bee
31c60 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 n finalized can
31c70 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 result in undefi
31c80 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 ned and.** undes
31c90 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 irable behavior
31ca0 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 such as segfault
31cb0 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 s and heap corru
31cc0 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ption..*/.SQLITE
31cd0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
31ce0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
31cf0 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 finalize(sqlite3
31d00 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
31d10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
31d20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 Reset A Prepared
31d30 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
31d40 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
31d50 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
31d60 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 The sqlite3_rese
31d70 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 t() function is
31d80 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 called to reset
31d90 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
31da0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 ement].** object
31db0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 back to its ini
31dc0 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 tial state, read
31dd0 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 y to be re-execu
31de0 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c ted..** ^Any SQL
31df0 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 statement varia
31e00 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 bles that had va
31e10 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 lues bound to th
31e20 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 em using.** the
31e30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
31e40 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e ob | sqlite3_bin
31e50 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 d_*() API] retai
31e60 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a n their values..
31e70 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f ** Use [sqlite3_
31e80 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 clear_bindings()
31e90 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 ] to reset the b
31ea0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e indings..**.** ^
31eb0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
31ec0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 et(S)] interface
31ed0 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 resets the [pre
31ee0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
31ef0 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 S.** back to th
31f00 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 e beginning of i
31f10 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a ts program..**.*
31f20 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 * ^If the most r
31f30 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
31f40 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
31f50 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 for the.** [prep
31f60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
31f70 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 S returned [SQLI
31f80 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 TE_ROW] or [SQLI
31f90 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 TE_DONE],.** or
31fa0 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 if [sqlite3_step
31fb0 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 (S)] has never b
31fc0 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 efore been calle
31fd0 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 d on S,.** then
31fe0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
31ff0 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 )] returns [SQLI
32000 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 TE_OK]..**.** ^I
32010 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
32020 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
32030 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 e3_step(S)] for
32040 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
32050 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e statement] S in
32060 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 dicated an error
32070 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 , then.** [sqlit
32080 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 e3_reset(S)] ret
32090 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 urns an appropri
320a0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ate [error code]
320b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 ..**.** ^The [sq
320c0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
320d0 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e interface does n
320e0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 ot change the va
320f0 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b lues.** of any [
32100 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
32110 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 b|bindings] on t
32120 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
32130 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 tement] S..*/.SQ
32140 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
32150 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
32160 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 te3_reset(sqlite
32170 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
32180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
32190 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 Create Or Redef
321a0 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e ine SQL Function
321b0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
321c0 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f function creatio
321d0 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b n routines}.** K
321e0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 EYWORDS: {applic
321f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
32200 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b L function}.** K
32210 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 EYWORDS: {applic
32220 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
32230 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 L functions}.**
32240 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
32250 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e **.** ^These fun
32260 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 ctions (collecti
32270 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 vely known as "f
32280 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e unction creation
32290 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 routines").** a
322a0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 re used to add S
322b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 QL functions or
322c0 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f aggregates or to
322d0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 redefine the be
322e0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 havior.** of exi
322f0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 sting SQL functi
32300 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
32310 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 s. The only dif
32320 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e ferences between
32330 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e .** these routin
32340 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 es are the text
32350 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 encoding expecte
32360 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 d for.** the sec
32370 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 ond parameter (t
32380 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 he name of the f
32390 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 unction being cr
323a0 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 eated).** and th
323b0 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 e presence or ab
323c0 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 sence of a destr
323d0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 uctor callback f
323e0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 or.** the applic
323f0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 ation data point
32400 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 er..**.** ^The f
32410 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
32420 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 s the [database
32430 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 connection] to w
32440 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 hich the SQL.**
32450 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 function is to b
32460 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e e added. ^If an
32470 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 application use
32480 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 s more than one
32490 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
324a0 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c ection then appl
324b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
324c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 SQL functions mu
324d0 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 st be added.** t
324e0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 o each database
324f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 connection separ
32500 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ately..**.** ^Th
32510 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
32520 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f er is the name o
32530 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 f the SQL functi
32540 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 on to be created
32550 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 or.** redefined
32560 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f . ^The length o
32570 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 f the name is li
32580 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 mited to 255 byt
32590 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a es in a UTF-8.**
325a0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c representation,
325b0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 exclusive of th
325c0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f e zero-terminato
325d0 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 r. ^Note that t
325e0 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 he name.** lengt
325f0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 h limit is in UT
32600 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 F-8 bytes, not c
32610 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 haracters nor UT
32620 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a F-16 bytes. .**
32630 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f ^Any attempt to
32640 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 create a functi
32650 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 on with a longer
32660 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 name.** will re
32670 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f sult in [SQLITE_
32680 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 MISUSE] being re
32690 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 turned..**.** ^T
326a0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
326b0 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 er (nArg).** is
326c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 the number of ar
326d0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 guments that the
326e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
326f0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 .** aggregate ta
32700 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 kes. ^If this pa
32710 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 rameter is -1, t
32720 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hen the SQL func
32730 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
32740 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e gate may take an
32750 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 y number of argu
32760 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 ments between 0
32770 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a and the limit.**
32780 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 set by [sqlite3
32790 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f _limit]([SQLITE_
327a0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 LIMIT_FUNCTION_A
327b0 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 RG]). If the th
327c0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ird.** parameter
327d0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 is less than -1
327e0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e or greater than
327f0 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 127 then the be
32800 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 havior is.** und
32810 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
32820 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
32830 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 ter, eTextRep, s
32840 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a pecifies what.**
32850 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 [SQLITE_UTF8 |
32860 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 text encoding] t
32870 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e his SQL function
32880 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 prefers for.**
32890 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 its parameters.
328a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
328b0 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 should set this
328c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
328d0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 [SQLITE_UTF16LE
328e0 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f ] if the functio
328f0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
32900 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 invokes .** [sq
32910 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
32920 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 16le()] on an in
32930 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f put, or [SQLITE_
32940 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a UTF16BE] if the.
32950 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
32960 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 n invokes [sqlit
32970 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 e3_value_text16b
32980 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 e()] on an input
32990 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f , or.** [SQLITE_
329a0 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 UTF16] if [sqlit
329b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
329c0 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b )] is used, or [
329d0 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 SQLITE_UTF8].**
329e0 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 otherwise. ^The
329f0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 same SQL functi
32a00 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 on may be regist
32a10 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 ered multiple ti
32a20 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 mes using.** dif
32a30 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 ferent preferred
32a40 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c text encodings,
32a50 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 with different
32a60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
32a70 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f for.** each enco
32a80 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d ding..** ^When m
32a90 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e ultiple implemen
32aa0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 tations of the s
32ab0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 ame function are
32ac0 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 available, SQLi
32ad0 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 te.** will pick
32ae0 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 the one that inv
32af0 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 olves the least
32b00 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 amount of data c
32b10 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a onversion..**.**
32b20 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 ^The fourth par
32b30 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f ameter may optio
32b40 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 nally be ORed wi
32b50 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 th [SQLITE_DETER
32b60 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 MINISTIC].** to
32b70 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 signal that the
32b80 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c function will al
32b90 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 ways return the
32ba0 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 same result give
32bb0 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e n.** the same in
32bc0 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 puts within a si
32bd0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 ngle SQL stateme
32be0 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 nt. Most SQL fu
32bf0 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 nctions are.** d
32c00 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 eterministic. T
32c10 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e he built-in [ran
32c20 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 dom()] SQL funct
32c30 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c ion is an exampl
32c40 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 e of a.** functi
32c50 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 on that is not d
32c60 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 eterministic. T
32c70 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 he SQLite query
32c80 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 planner is able
32c90 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 to.** perform ad
32ca0 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a ditional optimiz
32cb0 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d ations on determ
32cc0 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e inistic function
32cd0 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 s, so use.** of
32ce0 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 the [SQLITE_DETE
32cf0 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 RMINISTIC] flag
32d00 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 is recommended w
32d10 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a here possible..*
32d20 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 *.** ^(The fifth
32d30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e parameter is an
32d40 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 arbitrary point
32d50 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 er. The impleme
32d60 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a ntation of the.*
32d70 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 * function can g
32d80 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 ain access to th
32d90 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 is pointer using
32da0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 [sqlite3_user_d
32db0 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 ata()].)^.**.**
32dc0 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 ^The sixth, seve
32dd0 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 nth and eighth p
32de0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 arameters, xFunc
32df0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e , xStep and xFin
32e00 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 al, are.** point
32e10 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 ers to C-languag
32e20 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 e functions that
32e30 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 implement the S
32e40 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
32e50 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 * aggregate. ^A
32e60 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 scalar SQL funct
32e70 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 ion requires an
32e80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
32e90 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 f the xFunc.** c
32ea0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 allback only; NU
32eb0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 LL pointers must
32ec0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
32ed0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e e xStep and xFin
32ee0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 al.** parameters
32ef0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 . ^An aggregate
32f00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 SQL function req
32f10 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 uires an impleme
32f20 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 ntation of xStep
32f30 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 .** and xFinal a
32f40 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 nd NULL pointer
32f50 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 must be passed f
32f60 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 or xFunc. ^To de
32f70 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 lete an existing
32f80 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e .** SQL function
32f90 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 or aggregate, p
32fa0 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 ass NULL pointer
32fb0 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 s for all three
32fc0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c function.** call
32fd0 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 backs..**.** ^(I
32fe0 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 f the ninth para
32ff0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
33000 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
33010 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c _v2() is not NUL
33020 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 L,.** then it is
33030 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 destructor for
33040 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
33050 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a data pointer. .*
33060 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 * The destructor
33070 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e is invoked when
33080 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 the function is
33090 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 deleted, either
330a0 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 by being.** ove
330b0 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 rloaded or when
330c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
330d0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 nection closes.)
330e0 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 ^.** ^The destru
330f0 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 ctor is also inv
33100 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c oked if the call
33110 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 to.** sqlite3_c
33120 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
33130 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 2() fails..** ^W
33140 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 hen the destruct
33150 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 or callback of t
33160 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 he tenth paramet
33170 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 er is invoked, i
33180 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 t.** is passed a
33190 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
331a0 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 which is a copy
331b0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
331c0 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 ion data .** poi
331d0 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 nter which was t
331e0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 he fifth paramet
331f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 er to sqlite3_cr
33200 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 eate_function_v2
33210 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 ()..**.** ^It is
33220 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 permitted to re
33230 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 gister multiple
33240 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
33250 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 of the same.** f
33260 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 unctions with th
33270 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 e same name but
33280 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 with either diff
33290 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 ering numbers of
332a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 .** arguments or
332b0 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 differing prefe
332c0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
332d0 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 ngs. ^SQLite wi
332e0 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d ll use.** the im
332f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 plementation tha
33300 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d t most closely m
33310 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 atches the way i
33320 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 n which the.** S
33330 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 QL function is u
33340 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f sed. ^A functio
33350 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
33360 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 with a non-nega
33370 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 tive.** nArg par
33380 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 ameter is a bett
33390 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 er match than a
333a0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
333b0 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 ntation with.**
333c0 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e a negative nArg.
333d0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 ^A function wh
333e0 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 ere the preferre
333f0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a d text encoding.
33400 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 ** matches the d
33410 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 atabase encoding
33420 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 is a better.**
33430 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e match than a fun
33440 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
33450 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 encoding is diff
33460 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 erent. .** ^A f
33470 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
33480 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 e encoding diffe
33490 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e rence is between
334a0 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 UTF16le and UTF
334b0 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 16be.** is a clo
334c0 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 ser match than a
334d0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
334e0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 the encoding dif
334f0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 ference is.** be
33500 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 tween UTF8 and U
33510 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 TF16..**.** ^Bui
33520 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 lt-in functions
33530 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 may be overloade
33540 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 d by new applica
33550 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
33560 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 ctions..**.** ^A
33570 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
33580 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 fined function i
33590 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 s permitted to c
335a0 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c all other.** SQL
335b0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 ite interfaces.
335c0 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 However, such c
335d0 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a alls must not.**
335e0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 close the datab
335f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e ase connection n
33600 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 or finalize or r
33610 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 eset the prepare
33620 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 d.** statement i
33630 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 n which the func
33640 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e tion is running.
33650 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
33660 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
33670 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 L sqlite3_create
33680 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c _function(. sql
33690 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
336a0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
336b0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
336c0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
336d0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
336e0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
336f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
33700 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
33710 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
33720 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
33730 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
33740 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
33750 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
33760 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
33770 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ).);.SQLITE_API
33780 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
33790 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 LL sqlite3_creat
337a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 e_function16(.
337b0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
337c0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 onst void *zFunc
337d0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
337e0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
337f0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
33800 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
33810 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
33820 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
33830 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
33840 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
33850 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
33860 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
33870 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
33880 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
33890 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 xt*).);.SQLITE_A
338a0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
338b0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 DCALL sqlite3_cr
338c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 eate_function_v2
338d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
338e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
338f0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 FunctionName,.
33900 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 int nArg,. int
33910 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 eTextRep,. void
33920 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 *pApp,. void (
33930 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f *xFunc)(sqlite3_
33940 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
33950 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
33960 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 void (*xStep)(s
33970 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
33980 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
33990 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
339a0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 Final)(sqlite3_c
339b0 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 ontext*),. void
339c0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 (*xDestroy)(void
339d0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *).);../*.** CAP
339e0 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f I3REF: Text Enco
339f0 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 dings.**.** Thes
33a00 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e e constant defin
33a10 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 e integer codes
33a20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 that represent t
33a30 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 he various.** te
33a40 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 xt encodings sup
33a50 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 ported by SQLite
33a60 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
33a70 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 ITE_UTF8
33a80 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 1 /* IMP:
33a90 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f R-37514-35566 */
33aa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
33ab0 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 UTF16LE 2
33ac0 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 /* IMP: R-03
33ad0 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 371-37637 */.#de
33ae0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
33af0 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20 20 6BE 3
33b00 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d /* IMP: R-51971-
33b10 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 34154 */.#define
33b20 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 SQLITE_UTF16
33b30 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 4 /* U
33b40 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f se native byte o
33b50 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rder */.#define
33b60 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 SQLITE_ANY
33b70 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 5 /* De
33b80 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 precated */.#def
33b90 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
33ba0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f _ALIGNED 8 /
33bb0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
33bc0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 _collation only
33bd0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
33be0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 EF: Function Fla
33bf0 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 gs.**.** These c
33c00 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 onstants may be
33c10 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 ORed together wi
33c20 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 th the .** [SQLI
33c30 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 TE_UTF8 | prefer
33c40 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
33c50 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 g] as the fourth
33c60 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
33c70 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
33c80 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 function()], [sq
33c90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
33ca0 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a ction16()], or.*
33cb0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
33cc0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d e_function_v2()]
33cd0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
33ce0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 ITE_DETERMINISTI
33cf0 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a C 0x800../*.*
33d00 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 * CAPI3REF: Depr
33d10 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 ecated Functions
33d20 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a .** DEPRECATED.*
33d30 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
33d40 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 ions are [deprec
33d50 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 ated]. In order
33d60 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 to maintain.**
33d70 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
33d80 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 ibility with old
33d90 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 er code, these f
33da0 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 unctions continu
33db0 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 e .** to be supp
33dc0 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c orted. However,
33dd0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e new application
33de0 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a s should avoid.*
33df0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 * the use of the
33e00 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 se functions. T
33e10 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 o encourage prog
33e20 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 rammers to avoid
33e30 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 .** these functi
33e40 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 ons, we will not
33e50 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68 explain what th
33e60 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 ey do..*/.#ifnde
33e70 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 f SQLITE_OMIT_DE
33e80 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f PRECATED.SQLITE_
33e90 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
33ea0 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 CATED int SQLITE
33eb0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
33ec0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 _aggregate_count
33ed0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
33ee0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 *);.SQLITE_API S
33ef0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
33f00 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
33f10 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 70 69 ALL sqlite3_expi
33f20 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 red(sqlite3_stmt
33f30 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 *);.SQLITE_API S
33f40 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
33f50 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
33f60 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61 6e ALL sqlite3_tran
33f70 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 sfer_bindings(sq
33f80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c lite3_stmt*, sql
33f90 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c ite3_stmt*);.SQL
33fa0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 ITE_API SQLITE_D
33fb0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 EPRECATED int SQ
33fc0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
33fd0 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f ite3_global_reco
33fe0 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 ver(void);.SQLIT
33ff0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 E_API SQLITE_DEP
34000 52 45 43 41 54 45 44 20 76 6f 69 64 20 53 51 4c RECATED void SQL
34010 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
34020 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e te3_thread_clean
34030 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 up(void);.SQLITE
34040 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 _API SQLITE_DEPR
34050 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 ECATED int SQLIT
34060 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
34070 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 3_memory_alarm(v
34080 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
34090 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c ite3_int64,int),
340a0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
340b0 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c void*,sql
340c0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e ite3_int64);.#en
340d0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
340e0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 REF: Obtaining S
340f0 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 QL Values.** MET
34100 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c HOD: sqlite3_val
34110 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c ue.**.** The C-l
34120 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e anguage implemen
34130 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 tation of SQL fu
34140 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
34150 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 egates uses.** t
34160 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 his set of inter
34170 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f face routines to
34180 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 access the para
34190 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a meter values on.
341a0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 ** the function
341b0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a or aggregate. .
341c0 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 **.** The xFunc
341d0 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 (for scalar func
341e0 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 tions) or xStep
341f0 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 (for aggregates)
34200 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 parameters.** t
34210 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
34220 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
34230 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
34240 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
34250 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 ** define callba
34260 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 cks that impleme
34270 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
34280 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
34290 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 tes..** The 3rd
342a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
342b0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 se callbacks is
342c0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
342d0 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 ters to.** [prot
342e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
342f0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 lue] objects. T
34300 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c here is one [sql
34310 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
34320 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 ct for.** each p
34330 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
34340 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 SQL function. T
34350 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
34360 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 e used to.** ext
34370 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d ract values from
34380 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
34390 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a lue] objects..**
343a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
343b0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 es work only wit
343c0 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c h [protected sql
343d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
343e0 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 cts..** Any atte
343f0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 mpt to use these
34400 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 routines on an
34410 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
34420 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f ite3_value].** o
34430 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e bject results in
34440 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
34450 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ior..**.** ^Thes
34460 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
34470 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f just like the co
34480 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c rresponding [col
34490 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
344a0 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 ions].** except
344b0 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 that these routi
344c0 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c nes take a singl
344d0 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c e [protected sql
344e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
344f0 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e ct.** pointer in
34500 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 stead of a [sqli
34510 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 te3_stmt*] point
34520 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 er and an intege
34530 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e r column number.
34540 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
34550 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
34560 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 () interface ext
34570 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 racts a UTF-16 s
34580 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 tring.** in the
34590 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 native byte-orde
345a0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 r of the host ma
345b0 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 chine. ^The.**
345c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
345d0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c xt16be() and sql
345e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
345f0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 6le() interfaces
34600 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d .** extract UTF-
34610 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 16 strings as bi
34620 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 g-endian and lit
34630 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 tle-endian respe
34640 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e ctively..**.** ^
34650 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c (The sqlite3_val
34660 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 ue_numeric_type(
34670 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 ) interface atte
34680 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a mpts to apply.**
34690 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 numeric affinit
346a0 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 y to the value.
346b0 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 This means that
346c0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a an attempt is.*
346d0 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 * made to conver
346e0 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 t the value to a
346f0 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f n integer or flo
34700 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 ating point. If
34710 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 .** such a conve
34720 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c rsion is possibl
34730 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f e without loss o
34740 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 f information (i
34750 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 n other.** words
34760 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 , if the value i
34770 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 s a string that
34780 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d looks like a num
34790 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ber).** then the
347a0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 conversion is p
347b0 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 erformed. Other
347c0 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 wise no conversi
347d0 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 on occurs..** Th
347e0 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 e [SQLITE_INTEGE
347f0 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 R | datatype] af
34800 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 ter conversion i
34810 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a s returned.)^.**
34820 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 .** Please pay p
34830 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 articular attent
34840 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 ion to the fact
34850 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 that the pointer
34860 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f returned.** fro
34870 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 m [sqlite3_value
34880 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 _blob()], [sqlit
34890 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d e3_value_text()]
348a0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
348b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d _value_text16()]
348c0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 can be invalida
348d0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 ted by a subsequ
348e0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ent call to.** [
348f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
34900 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 tes()], [sqlite3
34910 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 _value_bytes16()
34920 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
34930 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
34940 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
34950 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a text16()]..**.**
34960 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
34970 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
34980 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
34990 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 ead as.** the SQ
349a0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 L function that
349b0 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 supplied the [sq
349c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 lite3_value*] pa
349d0 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c rameters..*/.SQL
349e0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
349f0 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 id *SQLITE_STDCA
34a00 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 LL sqlite3_value
34a10 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 _blob(sqlite3_va
34a20 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
34a30 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
34a40 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c CALL sqlite3_val
34a50 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 ue_bytes(sqlite3
34a60 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
34a70 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
34a80 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
34a90 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 value_bytes16(sq
34aa0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
34ab0 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 QLITE_API double
34ac0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
34ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f sqlite3_value_do
34ae0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c uble(sqlite3_val
34af0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
34b00 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
34b10 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ALL sqlite3_valu
34b20 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 e_int(sqlite3_va
34b30 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
34b40 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 I sqlite3_int64
34b50 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
34b60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
34b70 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 64(sqlite3_value
34b80 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 *);.SQLITE_API c
34b90 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 onst unsigned ch
34ba0 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 ar *SQLITE_STDCA
34bb0 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 LL sqlite3_value
34bc0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 _text(sqlite3_va
34bd0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
34be0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 I const void *SQ
34bf0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
34c00 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
34c10 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 6(sqlite3_value*
34c20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
34c30 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 nst void *SQLITE
34c40 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
34c50 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 _value_text16le(
34c60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
34c70 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
34c80 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 t void *SQLITE_S
34c90 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
34ca0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 alue_text16be(sq
34cb0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
34cc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
34cd0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
34ce0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 ite3_value_type(
34cf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
34d00 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
34d10 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
34d20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d qlite3_value_num
34d30 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 eric_type(sqlite
34d40 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 3_value*);../*.*
34d50 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 * CAPI3REF: Find
34d60 69 6e 67 20 54 68 65 20 53 75 62 74 79 70 65 20 ing The Subtype
34d70 4f 66 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a Of SQL Values.**
34d80 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
34d90 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 _value.**.** The
34da0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 sqlite3_value_s
34db0 75 62 74 79 70 65 28 56 29 20 66 75 6e 63 74 69 ubtype(V) functi
34dc0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 on returns the s
34dd0 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20 61 6e ubtype for.** an
34de0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 [application-de
34df0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
34e00 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56 2e 20 on] argument V.
34e10 20 54 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 The subtype.**
34e20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20 information can
34e30 62 65 20 75 73 65 64 20 74 6f 20 70 61 73 73 20 be used to pass
34e40 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75 6e 74 a limited amount
34e50 20 6f 66 20 63 6f 6e 74 65 78 74 20 66 72 6f 6d of context from
34e60 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75 6e 63 .** one SQL func
34e70 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72 2e tion to another.
34e80 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 Use the [sqlit
34e90 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70 e3_result_subtyp
34ea0 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 e()].** routine
34eb0 74 6f 20 73 65 74 20 74 68 65 20 73 75 62 74 79 to set the subty
34ec0 70 65 20 66 6f 72 20 74 68 65 20 72 65 74 75 72 pe for the retur
34ed0 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 n value of an SQ
34ee0 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a L function..**.*
34ef0 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 6e * SQLite makes n
34f00 6f 20 75 73 65 20 6f 66 20 73 75 62 74 79 70 65 o use of subtype
34f10 20 69 74 73 65 6c 66 2e 20 20 49 74 20 6d 65 72 itself. It mer
34f20 65 6c 79 20 70 61 73 73 65 73 20 74 68 65 20 73 ely passes the s
34f30 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 ubtype.** from t
34f40 68 65 20 72 65 73 75 6c 74 20 6f 66 20 6f 6e 65 he result of one
34f50 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 [application-de
34f60 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
34f70 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 on] into the.**
34f80 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68 65 72 input of another
34f90 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
34fa0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 53 51 4c unsigned int SQL
34fb0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
34fc0 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 te3_value_subtyp
34fd0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
34fe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
34ff0 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 72 65 EF: Copy And Fre
35000 65 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 e SQL Values.**
35010 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
35020 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 value.**.** ^The
35030 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 sqlite3_value_d
35040 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 up(V) interface
35050 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
35060 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
35070 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 ue].** object D
35080 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f and returns a po
35090 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 63 6f inter to that co
350a0 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 py. ^The [sqlit
350b0 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 72 6e e3_value] return
350c0 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 ed.** is a [prot
350d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
350e0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e lue] object even
350f0 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 if the input is
35100 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 not..** ^The sq
35110 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 lite3_value_dup(
35120 56 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 V) interface ret
35130 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 urns NULL if V i
35140 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a s NULL or if a.*
35150 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
35160 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a ion fails..**.**
35170 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^The sqlite3_va
35180 6c 75 65 5f 66 72 65 65 28 56 29 20 69 6e 74 65 lue_free(V) inte
35190 72 66 61 63 65 20 66 72 65 65 73 20 61 6e 20 5b rface frees an [
351a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
351b0 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 bject.** previou
351c0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f sly obtained fro
351d0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 m [sqlite3_value
351e0 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 _dup()]. ^If V
351f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
35200 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 r.** then sqlite
35210 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 3_value_free(V)
35220 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f is a harmless no
35230 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 -op..*/.SQLITE_A
35240 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 PI SQLITE_EXPERI
35250 4d 45 4e 54 41 4c 20 73 71 6c 69 74 65 33 5f 76 MENTAL sqlite3_v
35260 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44 alue *SQLITE_STD
35270 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c CALL sqlite3_val
35280 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c ue_dup(const sql
35290 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
352a0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
352b0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 EXPERIMENTAL voi
352c0 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c d SQLITE_STDCALL
352d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 sqlite3_value_f
352e0 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ree(sqlite3_valu
352f0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 e*);../*.** CAPI
35300 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 3REF: Obtain Agg
35310 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 regate Function
35320 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f Context.** METHO
35330 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 D: sqlite3_conte
35340 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 xt.**.** Impleme
35350 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 ntations of aggr
35360 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
35370 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 ons use this.**
35380 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 routine to alloc
35390 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 ate memory for s
353a0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 toring their sta
353b0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 te..**.** ^The f
353c0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 irst time the sq
353d0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
353e0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 context(C,N) rou
353f0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a tine is called .
35400 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 ** for a particu
35410 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 lar aggregate fu
35420 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a nction, SQLite.*
35430 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 * allocates N of
35440 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 memory, zeroes
35450 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c out that memory,
35460 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 and returns a p
35470 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
35480 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e new memory. ^On
35490 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 second and subs
354a0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a equent calls to.
354b0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 ** sqlite3_aggre
354c0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 gate_context() f
354d0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 or the same aggr
354e0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 egate function i
354f0 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 nstance,.** the
35500 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 same buffer is r
35510 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 eturned. Sqlite
35520 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
35530 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c ext() is normall
35540 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 y.** called once
35550 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 for each invoca
35560 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 tion of the xSte
35570 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 p callback and t
35580 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 hen one.** last
35590 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 time when the xF
355a0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 inal callback is
355b0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 invoked. ^(Whe
355c0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a n no rows match.
355d0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 ** an aggregate
355e0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 query, the xStep
355f0 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 () callback of t
35600 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e he aggregate fun
35610 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 ction.** impleme
35620 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 ntation is never
35630 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e called and xFin
35640 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 al() is called e
35650 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 xactly once..**
35660 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 In those cases,
35670 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
35680 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 e_context() migh
35690 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 t be called for
356a0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d the.** first tim
356b0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 e from within xF
356c0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 inal().)^.**.**
356d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 ^The sqlite3_agg
356e0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
356f0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ,N) routine retu
35700 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
35710 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 er .** when firs
35720 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 t called if N is
35730 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 less than or eq
35740 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 ual to zero or i
35750 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c f a memory.** al
35760 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 locate error occ
35770 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 urs..**.** ^(The
35780 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 amount of space
35790 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 allocated by sq
357a0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
357b0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a context(C,N) is.
357c0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 ** determined by
357d0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 the N parameter
357e0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 on first succes
357f0 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e sful call. Chan
35800 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 ging the.** valu
35810 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 e of N in subseq
35820 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c uent call to sql
35830 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
35840 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a ontext() within.
35850 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 ** the same aggr
35860 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 egate function i
35870 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 nstance will not
35880 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f resize the memo
35890 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e ry.** allocation
358a0 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 .)^ Within the
358b0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c xFinal callback,
358c0 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 it is customary
358d0 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 to set.** N=0 i
358e0 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 n calls to sqlit
358f0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
35900 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 text(C,N) so tha
35910 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 t no .** pointle
35920 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ss memory alloca
35930 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a tions occur..**.
35940 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d ** ^SQLite autom
35950 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 atically frees t
35960 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
35970 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 ted by .** sqlit
35980 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
35990 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 text() when the
359a0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 aggregate query
359b0 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a concludes..**.**
359c0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
359d0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 eter must be a c
359e0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 opy of the.** [s
359f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c qlite3_context |
35a00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f SQL function co
35a10 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 ntext] that is t
35a20 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
35a30 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 er.** to the xSt
35a40 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c ep or xFinal cal
35a50 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 lback routine th
35a60 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 at implements th
35a70 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 e aggregate.** f
35a80 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 unction..**.** T
35a90 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 his routine must
35aa0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
35ab0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
35ac0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 in which.** the
35ad0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
35ae0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
35af0 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 g..*/.SQLITE_API
35b00 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
35b10 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67 DCALL sqlite3_ag
35b20 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
35b30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
35b40 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a , int nBytes);..
35b50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
35b60 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 User Data For Fu
35b70 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f nctions.** METHO
35b80 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 D: sqlite3_conte
35b90 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 xt.**.** ^The sq
35ba0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
35bb0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
35bc0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a rns a copy of.**
35bd0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 the pointer tha
35be0 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 t was the pUserD
35bf0 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 ata parameter (t
35c00 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
35c10 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c ).** of the [sql
35c20 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
35c30 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b tion()].** and [
35c40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
35c50 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 unction16()] rou
35c60 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 tines that origi
35c70 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 nally.** registe
35c80 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 red the applicat
35c90 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 ion defined func
35ca0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 tion..**.** This
35cb0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 routine must be
35cc0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
35cd0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
35ce0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 which.** the app
35cf0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
35d00 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
35d10 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ning..*/.SQLITE_
35d20 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 API void *SQLITE
35d30 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
35d40 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 _user_data(sqlit
35d50 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f e3_context*);../
35d60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
35d70 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
35d80 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 on For Functions
35d90 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
35da0 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a te3_context.**.*
35db0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
35dc0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 ontext_db_handle
35dd0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
35de0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a urns a copy of.*
35df0 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f * the pointer to
35e00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
35e10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 onnection] (the
35e20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 1st parameter).*
35e30 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
35e40 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
35e50 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c n()].** and [sql
35e60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
35e70 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e tion16()] routin
35e80 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c es that original
35e90 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 ly.** registered
35ea0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
35eb0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f defined functio
35ec0 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 n..*/.SQLITE_API
35ed0 20 73 71 6c 69 74 65 33 20 2a 53 51 4c 49 54 45 sqlite3 *SQLITE
35ee0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
35ef0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 _context_db_hand
35f00 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 le(sqlite3_conte
35f10 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 xt*);../*.** CAP
35f20 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 I3REF: Function
35f30 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a Auxiliary Data.*
35f40 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
35f50 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 3_context.**.**
35f60 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
35f70 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28 may be used by (
35f80 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 non-aggregate) S
35f90 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a QL functions to.
35fa0 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 ** associate met
35fb0 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d adata with argum
35fc0 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 ent values. If t
35fd0 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 he same value is
35fe0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 passed to.** mu
35ff0 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f ltiple invocatio
36000 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 ns of the same S
36010 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 QL function duri
36020 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 ng query executi
36030 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d on, under.** som
36040 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 e circumstances
36050 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d the associated m
36060 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 etadata may be p
36070 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 reserved. An ex
36080 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 ample.** of wher
36090 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 e this might be
360a0 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 useful is in a r
360b0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f egular-expressio
360c0 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 n matching.** fu
360d0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 nction. The comp
360e0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 iled version of
360f0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 the regular expr
36100 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 ession can be st
36110 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 ored as.** metad
36120 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 ata associated w
36130 69 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 ith the pattern
36140 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 string. .** The
36150 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 n as long as the
36160 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 pattern string
36170 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 remains the same
36180 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 ,.** the compile
36190 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 d regular expres
361a0 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 sion can be reus
361b0 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a ed on multiple.*
361c0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 * invocations of
361d0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
361e0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 on..**.** ^The s
361f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
36200 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ta() interface r
36210 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
36220 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 to the metadata
36230 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 .** associated b
36240 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 y the sqlite3_se
36250 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 t_auxdata() func
36260 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 tion with the Nt
36270 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 h argument.** va
36280 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 lue to the appli
36290 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
362a0 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 unction. ^If the
362b0 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 re is no metadat
362c0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 a.** associated
362d0 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f with the functio
362e0 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 n argument, this
362f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 sqlite3_get_aux
36300 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 data() interface
36310 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 .** returns a NU
36320 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
36330 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
36340 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 et_auxdata(C,N,P
36350 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 ,X) interface sa
36360 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 ves P as metadat
36370 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a a for the N-th.*
36380 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 * argument of th
36390 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
363a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 fined function.
363b0 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 ^Subsequent.**
363c0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
363d0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e _get_auxdata(C,N
363e0 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 ) return P from
363f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a the most recent.
36400 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 ** sqlite3_set_a
36410 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 uxdata(C,N,P,X)
36420 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 call if the meta
36430 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 data is still va
36440 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 lid or.** NULL i
36450 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 f the metadata h
36460 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 as been discarde
36470 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 d..** ^After eac
36480 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 h call to sqlite
36490 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 3_set_auxdata(C,
364a0 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 N,P,X) where X i
364b0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 s not NULL,.** S
364c0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b QLite will invok
364d0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 e the destructor
364e0 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 function X with
364f0 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 parameter P exa
36500 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 ctly.** once, wh
36510 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 en the metadata
36520 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a is discarded..**
36530 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 SQLite is free
36540 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d to discard the m
36550 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 etadata at any t
36560 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 ime, including:
36570 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 <ul>.** <li> whe
36580 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 n the correspond
36590 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 ing function par
365a0 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 ameter changes,
365b0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 or.** <li> when
365c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
365d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 ] or [sqlite3_fi
365e0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c nalize()] is cal
365f0 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 led for the.**
36600 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e SQL statemen
36610 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 t, or.** <li> wh
36620 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 en sqlite3_set_a
36630 75 78 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f uxdata() is invo
36640 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 ked again on the
36650 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c same parameter,
36660 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 or.** <li> duri
36670 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 ng the original
36680 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
36690 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 ata() call when
366a0 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 a memory .**
366b0 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 allocation err
366c0 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e or occurs. </ul>
366d0 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 )^.**.** Note th
366e0 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e e last bullet in
366f0 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 particular. Th
36700 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 e destructor X i
36710 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 n .** sqlite3_se
36720 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c t_auxdata(C,N,P,
36730 58 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c X) might be call
36740 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 ed immediately,
36750 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 before the.** sq
36760 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
36770 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 a() interface ev
36780 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e en returns. Hen
36790 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 ce sqlite3_set_a
367a0 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 uxdata().** shou
367b0 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 ld be called nea
367c0 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 r the end of the
367d0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
367e0 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 entation and the
367f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 .** function imp
36800 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
36810 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 ld not make any
36820 75 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a use of P after.*
36830 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 * sqlite3_set_au
36840 78 64 61 74 61 28 29 20 68 61 73 20 62 65 65 6e xdata() has been
36850 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e called..**.** ^
36860 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 (In practice, me
36870 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 tadata is preser
36880 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 ved between func
36890 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a tion calls for.*
368a0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d * function param
368b0 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 63 eters that are c
368c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 ompile-time cons
368d0 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 tants, including
368e0 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 literal.** valu
368f0 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 es and [paramete
36900 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 rs] and expressi
36910 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f ons composed fro
36920 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a m the same.)^.**
36930 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
36940 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 es must be calle
36950 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
36960 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a thread in which.
36970 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 ** the SQL funct
36980 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
36990 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
369a0 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 id *SQLITE_STDCA
369b0 4c 4c 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 LL sqlite3_get_a
369c0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 uxdata(sqlite3_c
369d0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b ontext*, int N);
369e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
369f0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
36a00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
36a10 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ata(sqlite3_cont
36a20 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 ext*, int N, voi
36a30 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 d*, void (*)(voi
36a40 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 d*));.../*.** CA
36a50 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 PI3REF: Constant
36a60 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 s Defining Speci
36a70 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 al Destructor Be
36a80 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 havior.**.** The
36a90 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 se are special v
36aa0 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 alues for the de
36ab0 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 structor that is
36ac0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 passed in as th
36ad0 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d e.** final argum
36ae0 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 ent to routines
36af0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 like [sqlite3_re
36b00 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e sult_blob()]. ^
36b10 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f If the destructo
36b20 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 r.** argument is
36b30 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 SQLITE_STATIC,
36b40 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 it means that th
36b50 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 e content pointe
36b60 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a r is constant.**
36b70 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 and will never
36b80 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 change. It does
36b90 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 not need to be
36ba0 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 destroyed. ^The
36bb0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 .** SQLITE_TRANS
36bc0 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 IENT value means
36bd0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e that the conten
36be0 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 t will likely ch
36bf0 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e ange in.** the n
36c00 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 ear future and t
36c10 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c hat SQLite shoul
36c20 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 d make its own p
36c30 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a rivate copy of.*
36c40 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 * the content be
36c50 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a fore returning..
36c60 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 **.** The typede
36c70 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 f is necessary t
36c80 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 o work around pr
36c90 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 oblems in certai
36ca0 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 n.** C++ compile
36cb0 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 rs..*/.typedef v
36cc0 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 oid (*sqlite3_de
36cd0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 structor_type)(v
36ce0 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 oid*);.#define S
36cf0 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 QLITE_STATIC
36d00 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 ((sqlite3_dest
36d10 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 ructor_type)0).#
36d20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
36d30 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 ANSIENT ((sqli
36d40 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 te3_destructor_t
36d50 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 ype)-1)../*.** C
36d60 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 API3REF: Setting
36d70 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 The Result Of A
36d80 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a n SQL Function.*
36d90 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
36da0 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 3_context.**.**
36db0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
36dc0 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 re used by the x
36dd0 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 Func or xFinal c
36de0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a allbacks that.**
36df0 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 implement SQL f
36e00 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
36e10 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a regates. See.**
36e20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
36e30 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 _function()] and
36e40 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
36e50 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a _function16()].*
36e60 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c * for additional
36e70 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
36e80 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
36e90 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 ons work very mu
36ea0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 ch like the [par
36eb0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 ameter binding]
36ec0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e family of.** fun
36ed0 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 ctions used to b
36ee0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f ind values to ho
36ef0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e st parameters in
36f00 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
36f10 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 ents..** Refer t
36f20 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d o the [SQL param
36f30 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 eter] documentat
36f40 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ion for addition
36f50 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
36f60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
36f70 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 e3_result_blob()
36f80 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
36f90 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a the result from.
36fa0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ** an applicatio
36fb0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
36fc0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f on to be the BLO
36fd0 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 B whose content
36fe0 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f is pointed.** to
36ff0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 by the second p
37000 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 arameter and whi
37010 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f ch is N bytes lo
37020 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 ng where N is th
37030 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d e.** third param
37040 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 eter..**.** ^The
37050 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37060 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 20 61 6e zeroblob(C,N) an
37070 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
37080 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 43 2c 4e 29 _zeroblob64(C,N)
37090 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 73 .** interfaces s
370a0 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 et the result of
370b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
370c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
370d0 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 42 4c 4f n to be.** a BLO
370e0 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c B containing all
370f0 20 7a 65 72 6f 20 62 79 74 65 73 20 61 6e 64 20 zero bytes and
37100 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2e N bytes in size.
37110 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
37120 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c te3_result_doubl
37130 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 e() interface se
37140 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 ts the result fr
37150 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 om.** an applica
37160 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
37170 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c ction to be a fl
37180 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
37190 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 ue specified.**
371a0 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d by its 2nd argum
371b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ent..**.** ^The
371c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
371d0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 rror() and sqlit
371e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
371f0 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 6() functions.**
37200 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 cause the imple
37210 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 mented SQL funct
37220 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 ion to throw an
37230 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 exception..** ^S
37240 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 QLite uses the s
37250 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f tring pointed to
37260 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 by the.** 2nd p
37270 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 arameter of sqli
37280 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
37290 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 () or sqlite3_re
372a0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a sult_error16().*
372b0 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 * as the text of
372c0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
372d0 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 e. ^SQLite inte
372e0 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 rprets the error
372f0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 .** message stri
37300 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ng from sqlite3_
37310 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 result_error() a
37320 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 s UTF-8. ^SQLite
37330 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 .** interprets t
37340 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 he string from s
37350 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
37360 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 ror16() as UTF-1
37370 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 6 in native.** b
37380 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 yte order. ^If
37390 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
373a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
373b0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a esult_error().**
373c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
373d0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 lt_error16() is
373e0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 negative then SQ
373f0 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 Lite takes as th
37400 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 e error.** messa
37410 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 ge all text up t
37420 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 hrough the first
37430 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e zero character.
37440 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 .** ^If the thir
37450 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
37460 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
37470 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 ror() or.** sqli
37480 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
37490 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 16() is non-nega
374a0 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 tive then SQLite
374b0 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 takes that many
374c0 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 .** bytes (not c
374d0 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 haracters) from
374e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
374f0 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d r as the error m
37500 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 essage..** ^The
37510 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
37520 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 rror() and sqlit
37530 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
37540 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6().** routines
37550 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 make a private c
37560 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 opy of the error
37570 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 message text be
37580 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 fore.** they ret
37590 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 urn. Hence, the
375a0 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f calling functio
375b0 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 n can deallocate
375c0 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 or.** modify th
375d0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 e text after the
375e0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 y return without
375f0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 harm..** ^The s
37600 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
37610 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 ror_code() funct
37620 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 ion changes the
37630 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 error code.** re
37640 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 turned by SQLite
37650 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 as a result of
37660 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 an error in a fu
37670 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 nction. ^By def
37680 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 ault,.** the err
37690 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 or code is SQLIT
376a0 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 E_ERROR. ^A sub
376b0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 sequent call to
376c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
376d0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c rror().** or sql
376e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
376f0 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 r16() resets the
37700 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 error code to S
37710 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a QLITE_ERROR..**.
37720 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
37730 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f result_error_too
37740 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 big() interface
37750 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f causes SQLite to
37760 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 throw an.** err
37770 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 or indicating th
37780 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 at a string or B
37790 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 LOB is too long
377a0 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a to represent..**
377b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
377c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f _result_error_no
377d0 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 mem() interface
377e0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f causes SQLite to
377f0 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 throw an.** err
37800 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 or indicating th
37810 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f at a memory allo
37820 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a cation failed..*
37830 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
37840 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 3_result_int() i
37850 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
37860 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a e return value.*
37870 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 * of the applica
37880 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
37890 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 ction to be the
378a0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 32-bit signed in
378b0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 teger.** value g
378c0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 iven in the 2nd
378d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 argument..** ^Th
378e0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
378f0 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 _int64() interfa
37900 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 ce sets the retu
37910 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 rn value.** of t
37920 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
37930 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
37940 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 to be the 64-bit
37950 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
37960 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 ** value given i
37970 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 n the 2nd argume
37980 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 nt..**.** ^The s
37990 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 qlite3_result_nu
379a0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ll() interface s
379b0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 ets the return v
379c0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 alue.** of the a
379d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
379e0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
379f0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 e NULL..**.** ^T
37a00 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
37a10 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 t_text(), sqlite
37a20 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 3_result_text16(
37a30 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 ),.** sqlite3_re
37a40 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c sult_text16le(),
37a50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 and sqlite3_res
37a60 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 ult_text16be() i
37a70 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 nterfaces.** set
37a80 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
37a90 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 e of the applica
37aa0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
37ab0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 ction to be.** a
37ac0 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 text string whi
37ad0 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 ch is represente
37ae0 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d d as UTF-8, UTF-
37af0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 16 native byte o
37b00 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 rder,.** UTF-16
37b10 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f little endian, o
37b20 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 r UTF-16 big end
37b30 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c ian, respectivel
37b40 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 y..** ^The sqlit
37b50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34 e3_result_text64
37b60 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
37b70 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
37b80 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c ue of an.** appl
37b90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
37ba0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
37bb0 20 74 65 78 74 20 73 74 72 69 6e 67 20 69 6e 20 text string in
37bc0 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73 an encoding.** s
37bd0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
37be0 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73 74 29 fifth (and last)
37bf0 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 parameter, whic
37c00 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a h must be one.**
37c10 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 of [SQLITE_UTF8
37c20 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 ], [SQLITE_UTF16
37c30 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 ], [SQLITE_UTF16
37c40 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f BE], or [SQLITE_
37c50 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 UTF16LE]..** ^SQ
37c60 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 Lite takes the t
37c70 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 ext result from
37c80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
37c90 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 from.** the 2nd
37ca0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 parameter of the
37cb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37cc0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
37cd0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 ..** ^If the 3rd
37ce0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
37cf0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
37d00 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
37d10 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 s.** is negative
37d20 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 , then SQLite ta
37d30 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 kes result text
37d40 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 from the 2nd par
37d50 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 ameter.** throug
37d60 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f h the first zero
37d70 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e character..** ^
37d80 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d If the 3rd param
37d90 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
37da0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
37db0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 interfaces.** i
37dc0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
37dd0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 then as many byt
37de0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 es (not characte
37df0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a rs) of the text.
37e00 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 ** pointed to by
37e10 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
37e20 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 er are taken as
37e30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
37e40 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 defined.** funct
37e50 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 ion result. If
37e60 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
37e70 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 r is non-negativ
37e80 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 e, then it.** mu
37e90 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f st be the byte o
37ea0 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 ffset into the s
37eb0 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 tring where the
37ec0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 NUL terminator w
37ed0 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 ould.** appear i
37ee0 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 f the string whe
37ef0 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 re NUL terminate
37f00 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 d. If any NUL c
37f10 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a haracters occur.
37f20 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 ** in the string
37f30 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 at a byte offse
37f40 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 t that is less t
37f50 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 han the value of
37f60 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 the 3rd.** para
37f70 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 meter, then the
37f80 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
37f90 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d will contain em
37fa0 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 bedded NULs and
37fb0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 the.** result of
37fc0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 expressions ope
37fd0 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 rating on string
37fe0 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 s with embedded
37ff0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 NULs is undefine
38000 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 d..** ^If the 4t
38010 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
38020 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
38030 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
38040 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 es.** or sqlite3
38050 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 _result_blob is
38060 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
38070 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
38080 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 calls that.** fu
38090 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 nction as the de
380a0 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 structor on the
380b0 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 text or BLOB res
380c0 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a ult when it has.
380d0 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e ** finished usin
380e0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a g that result..*
380f0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 * ^If the 4th pa
38100 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
38110 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
38120 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f xt* interfaces o
38130 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f r to.** sqlite3_
38140 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
38150 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
38160 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ant SQLITE_STATI
38170 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a C, then SQLite.*
38180 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 * assumes that t
38190 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 he text or BLOB
381a0 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e result is in con
381b0 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 stant space and
381c0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 does not.** copy
381d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
381e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f the parameter no
381f0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 r call a destruc
38200 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 tor on the conte
38210 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 nt.** when it ha
38220 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 s finished using
38230 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a that result..**
38240 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 ^If the 4th par
38250 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
38260 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
38270 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
38280 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
38290 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 lt_blob is the s
382a0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 pecial constant
382b0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
382c0 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 .** then SQLite
382d0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
382e0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 the result into
382f0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 space obtained f
38300 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c rom.** from [sql
38310 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 ite3_malloc()] b
38320 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 efore it returns
38330 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
38340 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
38350 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 e() interface se
38360 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 ts the result of
38370 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
38380 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
38390 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 tion to be a cop
383a0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 y of the.** [unp
383b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
383c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 _value] object s
383d0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
383e0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 2nd parameter.
383f0 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ^The.** sqlite3_
38400 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 result_value() i
38410 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 nterface makes a
38420 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 copy of the [sq
38430 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 lite3_value].**
38440 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c so that the [sql
38450 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 ite3_value] spec
38460 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 ified in the par
38470 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 ameter may chang
38480 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c e or.** be deall
38490 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c ocated after sql
384a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
384b0 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 e() returns with
384c0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 out harm..** ^A
384d0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
384e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
384f0 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 may always be u
38500 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 sed where an.**
38510 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
38520 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
38530 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 ct is required,
38540 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e so either.** kin
38550 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 d of [sqlite3_va
38560 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 lue] object can
38570 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 be used with thi
38580 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a s interface..**.
38590 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 ** If these rout
385a0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
385b0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 from within the
385c0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
385d0 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 .** than the one
385e0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
385f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
38600 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 ned function tha
38610 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 t received.** th
38620 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 e [sqlite3_conte
38630 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 xt] pointer, the
38640 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
38650 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 efined..*/.SQLIT
38660 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 E_API void SQLIT
38670 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
38680 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 3_result_blob(sq
38690 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
386a0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
386b0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
386c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
386d0 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c id SQLITE_STDCAL
386e0 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 L sqlite3_result
386f0 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f _blob64(sqlite3_
38700 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76 context*,const v
38710 6f 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 oid*,.
38720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
38730 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c sqlite3_uint64,
38740 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
38750 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
38760 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
38770 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 sqlite3_result_d
38780 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f ouble(sqlite3_co
38790 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b ntext*, do