0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 rograms. If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 s file, then it
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 ite, is subject
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 erimental". Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 to SQLite. We
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 e changes.** to
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69 ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67 n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73 est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20 C-language API
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69 r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73 e. This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69 the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 ve source.** on
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72 how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73 faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 ion number) and
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 to "sqlite3.h"
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 ITE3_H_.#define
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 lude <stdarg.h>
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 /*.** Make sure
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61 ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69 bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75 de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 TE_API.# define
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20 _CDECL.# define
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66 TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20 ros are used in
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 e.** interfaces
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63 as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65 ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 ntal. New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63 d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20 ated interfaces
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 ity only. Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 ese macros used
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 sages when they
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 were used. But
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 magic ended up
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 generating such
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 a flurry of bug
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 reports.** that
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 e back to using
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 not defined by
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 n Numbers.**.**
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20 Lite3) and Y is
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72 _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 0 + Y*1000 + Z)
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 where X, Y, and
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69 * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 te will also.**
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 he release from
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69 which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77 ved. Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 system</a>. ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f m. ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31 UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20 .** hash of the
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72 entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 QLITE_VERSION
10a0: 20 20 20 20 20 22 33 2e 38 2e 31 31 22 0a 23 64 "3.8.11".#d
10b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 efine SQLITE_VER
10c0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 38 SION_NUMBER 3008
10d0: 30 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 011.#define SQLI
10e0: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20 TE_SOURCE_ID
10f0: 20 20 22 32 30 31 35 2d 30 37 2d 32 34 20 32 33 "2015-07-24 23
1100: 3a 32 38 3a 30 35 20 64 62 31 32 39 31 34 39 38 :28:05 db1291498
1110: 31 32 63 62 34 65 61 64 62 34 63 64 37 39 61 64 12cb4eadb4cd79ad
1120: 32 39 33 64 31 34 39 36 32 64 32 36 33 38 64 22 293d14962d2638d"
1130: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1140: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 : Run-Time Libra
1150: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 ry Version Numbe
1160: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 rs.** KEYWORDS:
1170: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c sqlite3_version,
1180: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 sqlite3_sourcei
1190: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e d.**.** These in
11a0: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 terfaces provide
11b0: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d the same inform
11c0: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 ation as the [SQ
11d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a LITE_VERSION],.*
11e0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f * [SQLITE_VERSIO
11f0: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b N_NUMBER], and [
1200: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
1210: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
1220: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 macros.** but a
1230: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 re associated wi
1240: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 th the library i
1250: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 nstead of the he
1260: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 ader file. ^(Ca
1270: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 utious.** progra
1280: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c mmers might incl
1290: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 ude assert() sta
12a0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 tements in their
12b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a application to.
12c0: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76 ** verify that v
12d0: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
12e0: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 y these interfac
12f0: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 es match the mac
1300: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 ros in.** the he
1310: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 69 ader, and thus i
1320: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61 nsure that the a
1330: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a pplication is.**
1340: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d compiled with m
1350: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 atching library
1360: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 and header files
1370: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 ..**.** <blockqu
1380: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 ote><pre>.** ass
1390: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 ert( sqlite3_lib
13a0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 version_number()
13b0: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e ==SQLITE_VERSION
13c0: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 _NUMBER );.** as
13d0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c sert( strcmp(sql
13e0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c ite3_sourceid(),
13f0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
1400: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 )==0 );.** asser
1410: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 t( strcmp(sqlite
1420: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 3_libversion(),S
1430: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d QLITE_VERSION)==
1440: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 0 );.** </pre></
1450: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
1460: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1470: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e _version[] strin
1480: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 g constant conta
1490: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 ins the text of
14a0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d [SQLITE_VERSION]
14b0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 .** macro. ^The
14c0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
14d0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ion() function r
14e0: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
14f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 to the.** to th
1500: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f e sqlite3_versio
1510: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 n[] string const
1520: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ant. The sqlite
1530: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 3_libversion().*
1540: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 * function is pr
1550: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 ovided for use i
1560: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c n DLLs since DLL
1570: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 users usually d
1580: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 o not have.** di
1590: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 rect access to s
15a0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 tring constants
15b0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 within the DLL.
15c0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
15d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
15e0: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 er() function re
15f0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 turns an integer
1600: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 equal to.** [SQ
1610: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
1620: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 BER]. ^The sqli
1630: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 te3_sourceid() f
1640: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1650: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
1660: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 a string consta
1670: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 nt whose value i
1680: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 s the same as th
1690: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f e .** [SQLITE_SO
16a0: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 URCE_ID] C prepr
16b0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a ocessor macro..*
16c0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
16d0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 sqlite_version()
16e0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f ] and [sqlite_so
16f0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 urce_id()]..*/.S
1700: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
1710: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 _EXTERN const ch
1720: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 ar sqlite3_versi
1730: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49 on[];.SQLITE_API
1740: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
1750: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
1760: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 te3_libversion(v
1770: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
1780: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
1790: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
17a0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 te3_sourceid(voi
17b0: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 d);.SQLITE_API i
17c0: 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
17d0: 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 L sqlite3_libver
17e0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 sion_number(void
17f0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1800: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 EF: Run-Time Lib
1810: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e rary Compilation
1820: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 Options Diagnos
1830: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 tics.**.** ^The
1840: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f sqlite3_compileo
1850: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e ption_used() fun
1860: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 ction returns 0
1870: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 or 1 .** indicat
1880: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20 ing whether the
1890: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e specified option
18a0: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 was defined at
18b0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 .** compile time
18c0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 . ^The SQLITE_
18d0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d prefix may be om
18e0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a itted from the .
18f0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 ** option name p
1900: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 assed to sqlite3
1910: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 _compileoption_u
1920: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e sed(). .**.** ^
1930: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 The sqlite3_comp
1940: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 ileoption_get()
1950: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 function allows
1960: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 iterating.** ove
1970: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 r the list of op
1980: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 tions that were
1990: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 defined at compi
19a0: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 le time by.** re
19b0: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 turning the N-th
19c0: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 compile time op
19d0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 tion string. ^I
19e0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 f N is out of ra
19f0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f nge,.** sqlite3_
1a00: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 compileoption_ge
1a10: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 t() returns a NU
1a20: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 LL pointer. ^Th
1a30: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 e SQLITE_ .** pr
1a40: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 efix is omitted
1a50: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 from any strings
1a60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a returned by .**
1a70: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1a80: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a option_get()..**
1a90: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 .** ^Support for
1aa0: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 the diagnostic
1ab0: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 functions sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 3_compileoption_
1ad0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 used().** and sq
1ae0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
1af0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 ion_get() may be
1b00: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 omitted by spec
1b10: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b ifying the .** [
1b20: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 SQLITE_OMIT_COMP
1b30: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d ILEOPTION_DIAGS]
1b40: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 option at compi
1b50: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 le time..**.** S
1b60: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e ee also: SQL fun
1b70: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 ctions [sqlite_c
1b80: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1b90: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c d()] and.** [sql
1ba0: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f ite_compileoptio
1bb0: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 n_get()] and the
1bc0: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e [compile_option
1bd0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 s pragma]..*/.#i
1be0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 fndef SQLITE_OMI
1bf0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f T_COMPILEOPTION_
1c00: 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 DIAGS.SQLITE_API
1c10: 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
1c20: 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 ALL sqlite3_comp
1c30: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 ileoption_used(c
1c40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e onst char *zOptN
1c50: 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ame);.SQLITE_API
1c60: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
1c70: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
1c80: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
1c90: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 n_get(int N);.#e
1ca0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
1cb0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 3REF: Test To Se
1cc0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 e If The Library
1cd0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a Is Threadsafe.*
1ce0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1cf0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 3_threadsafe() f
1d00: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1d10: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 zero if and only
1d20: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 if.** SQLite wa
1d30: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
1d40: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d mutexing code om
1d50: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 itted due to the
1d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 .** [SQLITE_THRE
1d70: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d ADSAFE] compile-
1d80: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e time option bein
1d90: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a g set to 0..**.*
1da0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 * SQLite can be
1db0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 compiled with or
1dc0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 without mutexes
1dd0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b . When.** the [
1de0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
1df0: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f E] C preprocesso
1e00: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 r macro is 1 or
1e10: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 2, mutexes.** ar
1e20: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 e enabled and SQ
1e30: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61 Lite is threadsa
1e40: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a fe. When the.**
1e50: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
1e60: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c AFE] macro is 0,
1e70: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 .** the mutexes
1e80: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 are omitted. W
1e90: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 ithout the mutex
1ea0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 es, it is not sa
1eb0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c fe.** to use SQL
1ec0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 ite concurrently
1ed0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 from more than
1ee0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a one thread..**.*
1ef0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 * Enabling mutex
1f00: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 es incurs a meas
1f10: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e urable performan
1f20: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 ce penalty..** S
1f30: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 o if speed is of
1f40: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e utmost importan
1f50: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e ce, it makes sen
1f60: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a se to disable.**
1f70: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 the mutexes. B
1f80: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 ut for maximum s
1f90: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 afety, mutexes s
1fa0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 hould be enabled
1fb0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c ..** ^The defaul
1fc0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f t behavior is fo
1fd0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 r mutexes to be
1fe0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 enabled..**.** T
1ff0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 his interface ca
2000: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 n be used by an
2010: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d application to m
2020: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68 ake sure that th
2030: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 e.** version of
2040: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 SQLite that it i
2050: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 s linking agains
2060: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 t was compiled w
2070: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 ith.** the desir
2080: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 ed setting of th
2090: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
20a0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a SAFE] macro..**.
20b0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
20c0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f e only reports o
20d0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 n the compile-ti
20e0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 me mutex setting
20f0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 .** of the [SQLI
2100: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 TE_THREADSAFE] f
2110: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 lag. If SQLite
2120: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
2130: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 .** SQLITE_THREA
2140: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 DSAFE=1 or =2 th
2150: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 en mutexes are e
2160: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c nabled by defaul
2170: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 t but.** can be
2180: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c fully or partial
2190: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e ly disabled usin
21a0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c g a call to [sql
21b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a ite3_config()].*
21c0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 * with the verbs
21d0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
21e0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b SINGLETHREAD], [
21f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
2200: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f LTITHREAD],.** o
2210: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 r [SQLITE_CONFIG
2220: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e _SERIALIZED]. ^
2230: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 (The return valu
2240: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 e of the.** sqli
2250: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 te3_threadsafe()
2260: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 function shows
2270: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 only the compile
2280: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 -time setting of
2290: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 .** thread safet
22a0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 y, not any run-t
22b0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 ime changes to t
22c0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 hat setting made
22d0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 by.** sqlite3_c
22e0: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 onfig(). In othe
22f0: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 r words, the ret
2300: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 urn value from s
2310: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
2320: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e e().** is unchan
2330: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 ged by calls to
2340: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
2350: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 .)^.**.** See th
2360: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
2370: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e e] documentation
2380: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
2390: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a information..*/.
23a0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
23b0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
23c0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 lite3_threadsafe
23d0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 (void);../*.** C
23e0: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
23f0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e e Connection Han
2400: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a dle.** KEYWORDS:
2410: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 {database conne
2420: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 ction} {database
2430: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a connections}.**
2440: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 .** Each open SQ
2450: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 Lite database is
2460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
2470: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
2480: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 instance of.** t
2490: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 he opaque struct
24a0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 ure named "sqlit
24b0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 e3". It is usef
24c0: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 ul to think of a
24d0: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 n sqlite3.** poi
24e0: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 nter as an objec
24f0: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 t. The [sqlite3
2500: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
2510: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e e3_open16()], an
2520: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 d.** [sqlite3_op
2530: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
2540: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 ces are its cons
2550: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 tructors, and [s
2560: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a qlite3_close()].
2570: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
2580: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 close_v2()] are
2590: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e its destructors.
25a0: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 There are many
25b0: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 other.** interf
25c0: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a aces (such as.**
25d0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
25e0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 e_v2()], [sqlite
25f0: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2600: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 n()], and.** [sq
2610: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
2620: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 ut()] to name bu
2630: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 t three) that ar
2640: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a e methods on an.
2650: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 ** sqlite3 objec
2660: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 t..*/.typedef st
2670: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c ruct sqlite3 sql
2680: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ite3;../*.** CAP
2690: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e I3REF: 64-Bit In
26a0: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b teger Types.** K
26b0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f EYWORDS: sqlite_
26c0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e int64 sqlite_uin
26d0: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 t64.**.** Becaus
26e0: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 e there is no cr
26f0: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 oss-platform way
2700: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 to specify 64-b
2710: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 it integer types
2720: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 .** SQLite inclu
2730: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 des typedefs for
2740: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 64-bit signed a
2750: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 nd unsigned inte
2760: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 gers..**.** The
2770: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e sqlite3_int64 an
2780: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 d sqlite3_uint64
2790: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 are the preferr
27a0: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 ed type definiti
27b0: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ons..** The sqli
27c0: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c te_int64 and sql
27d0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 ite_uint64 types
27e0: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 are supported f
27f0: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 or backwards.**
2800: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e compatibility on
2810: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ly..**.** ^The s
2820: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 qlite3_int64 and
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 sqlite_int64 ty
2840: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e pes can store in
2850: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 teger values.**
2860: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 between -9223372
2870: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 036854775808 and
2880: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 +92233720368547
2890: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 75807 inclusive.
28a0: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 ^The.** sqlite
28b0: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 3_uint64 and sql
28c0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 ite_uint64 types
28d0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 can store integ
28e0: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 er values .** be
28f0: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 tween 0 and +184
2900: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 4674407370955161
2910: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 5 inclusive..*/.
2920: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e #ifdef SQLITE_IN
2930: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 T64_TYPE. typed
2940: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f ef SQLITE_INT64_
2950: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 TYPE sqlite_int6
2960: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 4;. typedef uns
2970: 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 igned SQLITE_INT
2980: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 64_TYPE sqlite_u
2990: 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 int64;.#elif def
29a0: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c ined(_MSC_VER) |
29b0: 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c | defined(__BORL
29c0: 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 ANDC__). typede
29d0: 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 f __int64 sqlite
29e0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 _int64;. typede
29f0: 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 f unsigned __int
2a00: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 64 sqlite_uint64
2a10: 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 ;.#else. typede
2a20: 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 f long long int
2a30: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 sqlite_int64;.
2a40: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 typedef unsigned
2a50: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 long long int s
2a60: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 qlite_uint64;.#e
2a70: 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c ndif.typedef sql
2a80: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 ite_int64 sqlite
2a90: 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 3_int64;.typedef
2aa0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 sqlite_uint64 s
2ab0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a qlite3_uint64;..
2ac0: 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 /*.** If compili
2ad0: 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 ng for a process
2ae0: 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c or that lacks fl
2af0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 oating point sup
2b00: 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 port,.** substit
2b10: 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 ute integer for
2b20: 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a floating-point..
2b30: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 */.#ifdef SQLITE
2b40: 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 _OMIT_FLOATING_P
2b50: 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f OINT.# define do
2b60: 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 uble sqlite3_int
2b70: 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 64.#endif../*.**
2b80: 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 CAPI3REF: Closi
2b90: 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f ng A Database Co
2ba0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 nnection.** DEST
2bb0: 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a RUCTOR: sqlite3.
2bc0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2bd0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 e3_close() and s
2be0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
2bf0: 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 ) routines are d
2c00: 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f estructors.** fo
2c10: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 r the [sqlite3]
2c20: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c object..** ^Call
2c30: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f s to sqlite3_clo
2c40: 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 se() and sqlite3
2c50: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75 _close_v2() retu
2c60: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 rn [SQLITE_OK] i
2c70: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 f.** the [sqlite
2c80: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63 3] object is suc
2c90: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f cessfully destro
2ca0: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f yed and all asso
2cb0: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 ciated.** resour
2cc0: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 ces are dealloca
2cd0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ted..**.** ^If t
2ce0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
2cf0: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 ection is associ
2d00: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 ated with unfina
2d10: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a lized prepared.*
2d20: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 * statements or
2d30: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 unfinished sqlit
2d40: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 e3_backup object
2d50: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 s then sqlite3_c
2d60: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c lose().** will l
2d70: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73 eave the databas
2d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 e connection ope
2d90: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 n and return [SQ
2da0: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e LITE_BUSY]..** ^
2db0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 If sqlite3_close
2dc0: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 _v2() is called
2dd0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 with unfinalized
2de0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2df0: 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 ents.** and/or u
2e00: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 nfinished sqlite
2e10: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 3_backups, then
2e20: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2e30: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a nection becomes.
2e40: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 ** an unusable "
2e50: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 zombie" which wi
2e60: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
2e70: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
2e80: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 when the.** last
2e90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2ea0: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 ent is finalized
2eb0: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c or the last sql
2ec0: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a ite3_backup is.*
2ed0: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 * finished. The
2ee0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 sqlite3_close_v
2ef0: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 2() interface is
2f00: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
2f10: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c e with.** host l
2f20: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 anguages that ar
2f30: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 e garbage collec
2f40: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 ted, and where t
2f50: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 he order in whic
2f60: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 h.** destructors
2f70: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 are called is a
2f80: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 rbitrary..**.**
2f90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f Applications sho
2fa0: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e uld [sqlite3_fin
2fb0: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 alize | finalize
2fc0: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 ] all [prepared
2fd0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 statements],.**
2fe0: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c [sqlite3_blob_cl
2ff0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c ose | close] all
3000: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c [BLOB handles],
3010: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 and .** [sqlite
3020: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 3_backup_finish
3030: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 | finish] all [s
3040: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
3050: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 bjects associate
3060: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 d.** with the [s
3070: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 qlite3] object p
3080: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 rior to attempti
3090: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 ng to close the
30a0: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 object. ^If.**
30b0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
30c0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 () is called on
30d0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
30e0: 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 ection] that sti
30f0: 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 ll has.** outsta
3100: 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 nding [prepared
3110: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c statements], [BL
3120: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 OB handles], and
3130: 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f /or.** [sqlite3_
3140: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 backup] objects
3150: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 then it returns
3160: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 [SQLITE_OK] and
3170: 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e the deallocation
3180: 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73 .** of resources
3190: 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74 is deferred unt
31a0: 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 il all [prepared
31b0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 statements], [B
31c0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a LOB handles],.**
31d0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 and [sqlite3_ba
31e0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 ckup] objects ar
31f0: 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 e also destroyed
3200: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b ..**.** ^If an [
3210: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
3220: 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 69 is destroyed whi
3230: 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e le a transaction
3240: 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 is open,.** the
3250: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
3260: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f automatically ro
3270: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a lled back..**.**
3280: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 The C parameter
3290: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f to [sqlite3_clo
32a0: 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 se(C)] and [sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d te3_close_v2(C)]
32c0: 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 .** must be eith
32d0: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 er a NULL.** poi
32e0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 nter or an [sqli
32f0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e te3] object poin
3300: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 ter obtained.**
3310: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 from [sqlite3_op
3320: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
3330: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a open16()], or.**
3340: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
3350: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 2()], and not pr
3360: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e eviously closed.
3370: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c .** ^Calling sql
3380: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 ite3_close() or
3390: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
33a0: 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 () with a NULL p
33b0: 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 ointer.** argume
33c0: 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 nt is a harmless
33d0: 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 no-op..*/.SQLIT
33e0: 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
33f0: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
3400: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 _close(sqlite3*)
3410: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
3420: 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
3440: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
3450: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 ** The type for
3460: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
3470: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 ion..** This is
3480: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 legacy and depre
3490: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e cated. It is in
34a0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f cluded for histo
34b0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 rical.** compati
34c0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f bility and is no
34d0: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f t documented..*/
34e0: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 .typedef int (*s
34f0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 qlite3_callback)
3500: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a (void*,int,char*
3510: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a *, char**);../*.
3520: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 ** CAPI3REF: One
3530: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 -Step Query Exec
3540: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a ution Interface.
3550: 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
3560: 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e3.**.** The sql
3570: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 ite3_exec() inte
3580: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 rface is a conve
3590: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 nience wrapper a
35a0: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 round.** [sqlite
35b0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
35c0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
35d0: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
35e0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 finalize()],.**
35f0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 that allows an a
3600: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 pplication to ru
3610: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 n multiple state
3620: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 ments of SQL.**
3630: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 without having t
3640: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 o use a lot of C
3650: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 code. .**.** ^T
3660: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
3670: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 ) interface runs
3680: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 zero or more UT
3690: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 F-8 encoded,.**
36a0: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 semicolon-separa
36b0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 te SQL statement
36c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 s passed into it
36d0: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a s 2nd argument,.
36e0: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 ** in the contex
36f0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 t of the [databa
3700: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 se connection] p
3710: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 assed in as its
3720: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 1st.** argument.
3730: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 ^If the callba
3740: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 ck function of t
3750: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 he 3rd argument
3760: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 to.** sqlite3_ex
3770: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c ec() is not NULL
3780: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 , then it is inv
3790: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 oked for each re
37a0: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 sult row.** comi
37b0: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 ng out of the ev
37c0: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 aluated SQL stat
37d0: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 ements. ^The 4t
37e0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a h argument to.**
37f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3800: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 is relayed throu
3810: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 gh to the 1st ar
3820: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a gument of each.*
3830: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 * callback invoc
3840: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 ation. ^If the
3850: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 callback pointer
3860: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 to sqlite3_exec
3870: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 ().** is NULL, t
3880: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 hen no callback
3890: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 is ever invoked
38a0: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 and result rows
38b0: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a are.** ignored..
38c0: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 **.** ^If an err
38d0: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 or occurs while
38e0: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 evaluating the S
38f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 QL statements pa
3900: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c ssed into.** sql
3910: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 ite3_exec(), the
3920: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 n execution of t
3930: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 he current state
3940: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a ment stops and.*
3950: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 * subsequent sta
3960: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 tements are skip
3970: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 ped. ^If the 5t
3980: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
3990: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
39a0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 is not NULL the
39b0: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 n any error mess
39c0: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 age is written i
39d0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 nto memory obtai
39e0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
39f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 ite3_malloc()] a
3a00: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 nd passed back t
3a10: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 hrough the 5th p
3a20: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 arameter..** To
3a30: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 avoid memory lea
3a40: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 ks, the applicat
3a50: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b ion should invok
3a60: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 e [sqlite3_free(
3a70: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d )].** on error m
3a80: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 essage strings r
3a90: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 eturned through
3aa0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
3ab0: 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 r of.** of sqlit
3ac0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 e3_exec() after
3ad0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
3ae0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c e string is no l
3af0: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a onger needed..**
3b00: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 ^If the 5th par
3b10: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3b20: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 3_exec() is not
3b30: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f NULL and no erro
3b40: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 rs.** occur, the
3b50: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 n sqlite3_exec()
3b60: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 sets the pointe
3b70: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 r in its 5th par
3b80: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c ameter to.** NUL
3b90: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 L before returni
3ba0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e ng..**.** ^If an
3bb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3bc0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
3bd0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 non-zero, the s
3be0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
3bf0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
3c00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 SQLITE_ABORT wi
3c10: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 thout invoking t
3c20: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 he callback agai
3c30: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 n and.** without
3c40: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 running any sub
3c50: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 sequent SQL stat
3c60: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ements..**.** ^T
3c70: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 he 2nd argument
3c80: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 to the sqlite3_e
3c90: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 xec() callback f
3ca0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a unction is the.*
3cb0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 * number of colu
3cc0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
3cd0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 t. ^The 3rd arg
3ce0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c ument to the sql
3cf0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 ite3_exec().** c
3d00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 allback is an ar
3d10: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
3d20: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 to strings obtai
3d30: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a ned as if from.*
3d40: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
3d50: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 n_text()], one f
3d60: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 or each column.
3d70: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 ^If an element
3d80: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 of a.** result r
3d90: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 ow is NULL then
3da0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
3db0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 g string pointer
3dc0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 for the.** sqli
3dd0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 te3_exec() callb
3de0: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ack is a NULL po
3df0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 inter. ^The 4th
3e00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
3e10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3e20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 () callback is a
3e30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
3e40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 ers to strings w
3e50: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 here each.** ent
3e60: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 ry represents th
3e70: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 e name of corres
3e80: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 ponding result c
3e90: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 olumn as obtaine
3ea0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
3eb0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
3ec0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 ]..**.** ^If the
3ed0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 2nd parameter t
3ee0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
3ef0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
3f00: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a er, a pointer.**
3f10: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 to an empty str
3f20: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 ing, or a pointe
3f30: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 r that contains
3f40: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 only whitespace
3f50: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 and/or .** SQL c
3f60: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f omments, then no
3f70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
3f80: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e are evaluated an
3f90: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a d the database.*
3fa0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 * is not changed
3fb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 ..**.** Restrict
3fc0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ions:.**.** <ul>
3fd0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 .** <li> The app
3fe0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e lication must in
3ff0: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 sure that the 1s
4000: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
4010: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
4020: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 is a valid
4030: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 and open [datab
4040: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
4050: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 .** <li> The app
4060: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f lication must no
4070: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 t close the [dat
4080: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
4090: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a ] specified by.*
40a0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 * the 1st p
40b0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
40c0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 te3_exec() while
40d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
40e0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c is running..** <
40f0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 li> The applicat
4100: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 ion must not mod
4110: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 ify the SQL stat
4120: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 ement text passe
4130: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 d into.** t
4140: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
4150: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 of sqlite3_exec
4160: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 () while sqlite3
4170: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 _exec() is runni
4180: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a ng..** </ul>.*/.
4190: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
41a0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
41b0: 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 lite3_exec(. sq
41c0: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 lite3*,
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41e0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f /* An o
41f0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a pen database */.
4200: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 const char *sq
4210: 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 l,
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
4230: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 SQL to be evalua
4240: 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 ted */. int (*c
4250: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 allback)(void*,i
4260: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a nt,char**,char**
4270: 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 ), /* Callback
4280: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f function */. vo
4290: 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 id *,
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
42b0: 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 /* 1st
42c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c argument to call
42d0: 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a back */. char *
42e0: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 *errmsg
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4300: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 /* Error ms
4310: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a g written here *
4320: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
4330: 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 3REF: Result Cod
4340: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
4350: 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 {result code def
4360: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 initions}.**.**
4370: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 Many SQLite func
4380: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 tions return an
4390: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 integer result c
43a0: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 ode from the set
43b0: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 shown.** here i
43c0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 n order to indic
43d0: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 ate success or f
43e0: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 ailure..**.** Ne
43f0: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 w error codes ma
4400: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
4410: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
4420: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 SQLite..**.** S
4430: 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 ee also: [extend
4440: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 ed result code d
4450: 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 efinitions].*/.#
4460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b define SQLITE_OK
4470: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 0 /
4480: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 * Successful res
4490: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e ult */./* beginn
44a0: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 ing-of-error-cod
44b0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 es */.#define SQ
44c0: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 LITE_ERROR
44d0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 1 /* SQL err
44e0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 or or missing da
44f0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e tabase */.#defin
4500: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 e SQLITE_INTERNA
4510: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 L 2 /* Int
4520: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f ernal logic erro
4530: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 r in SQLite */.#
4540: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 define SQLITE_PE
4550: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f RM 3 /
4560: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 * Access permiss
4570: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 ion denied */.#d
4580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f efine SQLITE_ABO
4590: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a RT 4 /*
45a0: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e Callback routin
45b0: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 e requested an a
45c0: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 bort */.#define
45d0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 SQLITE_BUSY
45e0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 5 /* The d
45f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 atabase file is
4600: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e locked */.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 e SQLITE_LOCKED
4620: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 6 /* A t
4630: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 able in the data
4640: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a base is locked *
4650: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4660: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 _NOMEM 7
4670: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 /* A malloc()
4680: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e failed */.#defin
4690: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
46a0: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 Y 8 /* Att
46b0: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 empt to write a
46c0: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 readonly databas
46d0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
46e0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 ITE_INTERRUPT
46f0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 9 /* Operatio
4700: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 n terminated by
4710: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
4720: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t()*/.#define SQ
4730: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 LITE_IOERR
4740: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 10 /* Some ki
4750: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 nd of disk I/O e
4760: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f rror occurred */
4770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4780: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 CORRUPT 11
4790: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
47a0: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d disk image is m
47b0: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 alformed */.#def
47c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f ine SQLITE_NOTFO
47d0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 UND 12 /* U
47e0: 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e nknown opcode in
47f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f sqlite3_file_co
4800: 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 ntrol() */.#defi
4810: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 ne SQLITE_FULL
4820: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 13 /* In
4830: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 sertion failed b
4840: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 ecause database
4850: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 is full */.#defi
4860: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 ne SQLITE_CANTOP
4870: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e EN 14 /* Un
4880: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 able to open the
4890: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a database file *
48a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
48b0: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 _PROTOCOL 15
48c0: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f /* Database lo
48d0: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f ck protocol erro
48e0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
48f0: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 ITE_EMPTY
4900: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 16 /* Database
4910: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 is empty */.#de
4920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 fine SQLITE_SCHE
4930: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 MA 17 /*
4940: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 The database sch
4950: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 ema changed */.#
4960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f define SQLITE_TO
4970: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f OBIG 18 /
4980: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 * String or BLOB
4990: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 exceeds size li
49a0: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 mit */.#define S
49b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
49c0: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 19 /* Abort
49d0: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e due to constrain
49e0: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 t violation */.#
49f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 define SQLITE_MI
4a00: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f SMATCH 20 /
4a10: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d * Data type mism
4a20: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 atch */.#define
4a30: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 SQLITE_MISUSE
4a40: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 21 /* Libra
4a50: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 ry used incorrec
4a60: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 tly */.#define S
4a70: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 QLITE_NOLFS
4a80: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 22 /* Uses O
4a90: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 S features not s
4aa0: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 upported on host
4ab0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4ac0: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 TE_AUTH 2
4ad0: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 3 /* Authoriza
4ae0: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 tion denied */.#
4af0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f define SQLITE_FO
4b00: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f RMAT 24 /
4b10: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 * Auxiliary data
4b20: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f base format erro
4b30: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
4b40: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 ITE_RANGE
4b50: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 25 /* 2nd para
4b60: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
4b70: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e _bind out of ran
4b80: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ge */.#define SQ
4b90: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 LITE_NOTADB
4ba0: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 26 /* File op
4bb0: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 ened that is not
4bc0: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
4bd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4be0: 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32 TE_NOTICE 2
4bf0: 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 7 /* Notificat
4c00: 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 ions from sqlite
4c10: 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 3_log() */.#defi
4c20: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e ne SQLITE_WARNIN
4c30: 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61 G 28 /* Wa
4c40: 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 rnings from sqli
4c50: 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 te3_log() */.#de
4c60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 fine SQLITE_ROW
4c70: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 100 /*
4c80: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 sqlite3_step() h
4c90: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 as another row r
4ca0: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 eady */.#define
4cb0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 SQLITE_DONE
4cc0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 101 /* sqlit
4cd0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 e3_step() has fi
4ce0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 nished executing
4cf0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 */./* end-of-er
4d00: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a ror-codes */../*
4d10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 .** CAPI3REF: Ex
4d20: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f tended Result Co
4d30: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a des.** KEYWORDS:
4d40: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c {extended resul
4d50: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f t code definitio
4d60: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 ns}.**.** In its
4d70: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
4d80: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 ration, SQLite A
4d90: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 PI routines retu
4da0: 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74 rn one of 30 int
4db0: 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 eger.** [result
4dc0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 codes]. However
4dd0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 , experience has
4de0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 shown that many
4df0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 of.** these res
4e00: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f ult codes are to
4e10: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 o coarse-grained
4e20: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 . They do not p
4e30: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 rovide as.** muc
4e40: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 h information ab
4e50: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 out problems as
4e60: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 programmers migh
4e70: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 t like. In an e
4e80: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 ffort to.** addr
4e90: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 ess this, newer
4ea0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
4eb0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e te (version 3.3.
4ec0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 8 and later) inc
4ed0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 lude.** support
4ee0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 for additional r
4ef0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 esult codes that
4f00: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 provide more de
4f10: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 tailed informati
4f20: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f on.** about erro
4f30: 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74 65 6e rs. These [exten
4f40: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
4f50: 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 ] are enabled or
4f60: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 disabled.** on
4f70: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63 a per database c
4f80: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 onnection basis
4f90: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 using the.** [sq
4fa0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 lite3_extended_r
4fb0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 esult_codes()] A
4fc0: 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 74 PI. Or, the ext
4fd0: 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a ended code for.*
4fe0: 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e * the most recen
4ff0: 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65 20 6f t error can be o
5000: 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a btained using.**
5010: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 [sqlite3_extend
5020: 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a ed_errcode()]..*
5030: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5040: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 _IOERR_READ
5050: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5060: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 _IOERR | (1<<8))
5070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5080: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 IOERR_SHORT_READ
5090: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
50a0: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a IOERR | (2<<8)).
50b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
50c0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 OERR_WRITE
50d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
50e0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 OERR | (3<<8)).#
50f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5100: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 ERR_FSYNC
5110: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5120: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 ERR | (4<<8)).#d
5130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5140: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 RR_DIR_FSYNC
5150: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5160: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 RR | (5<<8)).#de
5170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
5180: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 R_TRUNCATE
5190: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
51a0: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 R | (6<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
51c0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 _FSTAT
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
51e0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 | (7<<8)).#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5200: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 UNLOCK
5210: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5220: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (8<<8)).#defin
5230: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 e SQLITE_IOERR_R
5240: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 DLOCK
5250: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5260: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (9<<8)).#define
5270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 SQLITE_IOERR_DE
5280: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
5290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
52a0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (10<<8)).#define
52b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c SQLITE_IOERR_BL
52c0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 OCKED
52d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
52e0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (11<<8)).#define
52f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f SQLITE_IOERR_NO
5300: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 MEM
5310: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5320: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (12<<8)).#define
5330: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 SQLITE_IOERR_AC
5340: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 CESS
5350: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5360: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (13<<8)).#define
5370: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 SQLITE_IOERR_CH
5380: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 ECKRESERVEDLOCK
5390: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
53a0: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (14<<8)).#define
53b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f SQLITE_IOERR_LO
53c0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CK
53d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
53e0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (15<<8)).#define
53f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c SQLITE_IOERR_CL
5400: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 OSE
5410: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5420: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (16<<8)).#define
5430: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 SQLITE_IOERR_DI
5440: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 R_CLOSE
5450: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5460: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (17<<8)).#define
5470: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
5480: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 MOPEN
5490: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
54a0: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (18<<8)).#define
54b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
54c0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 MSIZE
54d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
54e0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (19<<8)).#define
54f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
5500: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 MLOCK
5510: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5520: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (20<<8)).#define
5530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
5540: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 MMAP
5550: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5560: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (21<<8)).#define
5570: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 SQLITE_IOERR_SE
5580: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 EK
5590: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
55a0: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (22<<8)).#define
55b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 SQLITE_IOERR_DE
55c0: 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 LETE_NOENT
55d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
55e0: 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (23<<8)).#define
55f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d SQLITE_IOERR_MM
5600: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AP
5610: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5620: 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (24<<8)).#define
5630: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 SQLITE_IOERR_GE
5640: 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 TTEMPPATH
5650: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5660: 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (25<<8)).#define
5670: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f SQLITE_IOERR_CO
5680: 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20 NVPATH
5690: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
56a0: 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (26<<8)).#define
56b0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 SQLITE_LOCKED_S
56c0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 HAREDCACHE
56d0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c (SQLITE_LOCKED |
56e0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (1<<8)).#defin
56f0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 e SQLITE_BUSY_RE
5700: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 COVERY
5710: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 (SQLITE_BUSY
5720: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
5730: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 ne SQLITE_BUSY_S
5740: 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 NAPSHOT
5750: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 (SQLITE_BUSY
5760: 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 | (2<<8)).#def
5770: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
5780: 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 PEN_NOTEMPDIR
5790: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f (SQLITE_CANTO
57a0: 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 PEN | (1<<8)).#d
57b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
57c0: 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 TOPEN_ISDIR
57d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e (SQLITE_CAN
57e0: 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a TOPEN | (2<<8)).
57f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5800: 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 ANTOPEN_FULLPATH
5810: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
5820: 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 ANTOPEN | (3<<8)
5830: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5840: 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 _CANTOPEN_CONVPA
5850: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 TH (SQLITE
5860: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c _CANTOPEN | (4<<
5870: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5880: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 TE_CORRUPT_VTAB
5890: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
58a0: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c TE_CORRUPT | (1<
58b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
58c0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 ITE_READONLY_REC
58d0: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c OVERY (SQL
58e0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 ITE_READONLY | (
58f0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5900: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 QLITE_READONLY_C
5910: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 ANTLOCK (S
5920: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c QLITE_READONLY |
5930: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
5940: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 SQLITE_READONLY
5950: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 _ROLLBACK
5960: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 (SQLITE_READONLY
5970: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 | (3<<8)).#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e ne SQLITE_READON
5990: 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20 LY_DBMOVED
59a0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e (SQLITE_READON
59b0: 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 LY | (4<<8)).#de
59c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 fine SQLITE_ABOR
59d0: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 T_ROLLBACK
59e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 (SQLITE_ABOR
59f0: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 T | (2<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5a10: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 RAINT_CHECK
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5a30: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a RAINT | (1<<8)).
5a40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5a50: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 ONSTRAINT_COMMIT
5a60: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 HOOK (SQLITE_C
5a70: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c ONSTRAINT | (2<<
5a80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5a90: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f TE_CONSTRAINT_FO
5aa0: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 REIGNKEY (SQLI
5ab0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5ac0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (3<<8)).#define
5ad0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5ae0: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 T_FUNCTION (
5af0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5b00: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 T | (4<<8)).#def
5b10: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5b20: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 RAINT_NOTNULL
5b30: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5b40: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a RAINT | (5<<8)).
5b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5b60: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 ONSTRAINT_PRIMAR
5b70: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 YKEY (SQLITE_C
5b80: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c ONSTRAINT | (6<<
5b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5ba0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 TE_CONSTRAINT_TR
5bb0: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 IGGER (SQLI
5bc0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5bd0: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (7<<8)).#define
5be0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5bf0: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 T_UNIQUE (
5c00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5c10: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 T | (8<<8)).#def
5c20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5c30: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 RAINT_VTAB
5c40: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5c50: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a RAINT | (9<<8)).
5c60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5c70: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 ONSTRAINT_ROWID
5c80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
5c90: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c ONSTRAINT |(10<<
5ca0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5cb0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 TE_NOTICE_RECOVE
5cc0: 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49 R_WAL (SQLI
5cd0: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c TE_NOTICE | (1<<
5ce0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5cf0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 TE_NOTICE_RECOVE
5d00: 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 R_ROLLBACK (SQLI
5d10: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c TE_NOTICE | (2<<
5d20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5d30: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 TE_WARNING_AUTOI
5d40: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49 NDEX (SQLI
5d50: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c TE_WARNING | (1<
5d60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5d70: 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20 20 ITE_AUTH_USER
5d80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5d90: 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 ITE_AUTH | (1<<8
5da0: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ))../*.** CAPI3R
5db0: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 EF: Flags For Fi
5dc0: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f le Open Operatio
5dd0: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 ns.**.** These b
5de0: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e it values are in
5df0: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
5e00: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 n the.** 3rd par
5e10: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ameter to the [s
5e20: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
5e30: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a ] interface and.
5e40: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 ** in the 4th pa
5e50: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b rameter to the [
5e60: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 sqlite3_vfs.xOpe
5e70: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 n] method..*/.#d
5e80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5e90: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 N_READONLY
5ea0: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 0x00000001 /
5eb0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
5ec0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
5ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5ee0: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 N_READWRITE
5ef0: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 0x00000002 /
5f00: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
5f10: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
5f20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5f30: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 N_CREATE
5f40: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 0x00000004 /
5f50: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
5f60: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5f80: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 N_DELETEONCLOSE
5f90: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 0x00000008 /
5fa0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
5fb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
5fc0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 N_EXCLUSIVE
5fd0: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 0x00000010 /
5fe0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
5ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6000: 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 N_AUTOPROXY
6010: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 0x00000020 /
6020: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6040: 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 N_URI
6050: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 0x00000040 /
6060: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
6070: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
6080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6090: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 N_MEMORY
60a0: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 0x00000080 /
60b0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
60c0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
60d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
60e0: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 N_MAIN_DB
60f0: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 0x00000100 /
6100: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6120: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 N_TEMP_DB
6130: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 0x00000200 /
6140: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6150: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6160: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 N_TRANSIENT_DB
6170: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 0x00000400 /
6180: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
61a0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 N_MAIN_JOURNAL
61b0: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 0x00000800 /
61c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
61e0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 N_TEMP_JOURNAL
61f0: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 0x00001000 /
6200: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6220: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 N_SUBJOURNAL
6230: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 0x00002000 /
6240: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6260: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c N_MASTER_JOURNAL
6270: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 0x00004000 /
6280: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
6290: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
62a0: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 N_NOMUTEX
62b0: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 0x00008000 /
62c0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
62d0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
62e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
62f0: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 N_FULLMUTEX
6300: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 0x00010000 /
6310: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
6320: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
6330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6340: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 N_SHAREDCACHE
6350: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 0x00020000 /
6360: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
6370: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
6380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
6390: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 N_PRIVATECACHE
63a0: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 0x00040000 /
63b0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
63c0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
63d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
63e0: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 N_WAL
63f0: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 0x00080000 /
6400: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f * VFS only */../
6410: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 * Reserved:
6420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6430: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 0x00F00000 *
6440: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
6450: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 F: Device Charac
6460: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 teristics.**.**
6470: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 The xDeviceChara
6480: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f cteristics metho
6490: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 d of the [sqlite
64a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 3_io_methods].**
64b0: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 object returns
64c0: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 an integer which
64d0: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 is a vector of
64e0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c these.** bit val
64f0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 ues expressing I
6500: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 /O characteristi
6510: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 cs of the mass s
6520: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 torage.** device
6530: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 that holds the
6540: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 file that the [s
6550: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
6560: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e s].** refers to.
6570: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
6580: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
6590: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
65a0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
65b0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
65c0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
65d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
65e0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
65f0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
6600: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
6610: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
6620: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
6630: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
6640: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
6650: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
6660: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
6670: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
6680: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
6690: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
66a0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
66b0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
66c0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
66d0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
66e0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
66f0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
6700: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
6710: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
6720: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
6730: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6740: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
6750: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
6760: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
6770: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
6780: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
6790: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
67a0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 to xWrite(). T
67b0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
67c0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
67d0: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 ITE property mea
67e0: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 ns that.** after
67f0: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e reboot followin
6800: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 g a crash or pow
6810: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c er loss, the onl
6820: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 y bytes in a.**
6830: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 file that were w
6840: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 ritten at the ap
6850: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 plication level
6860: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 might have chang
6870: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 ed.** and that a
6880: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 djacent bytes, e
6890: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e ven bytes within
68a0: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 the same sector
68b0: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 are.** guarante
68c0: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 ed to be unchang
68d0: 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f ed. The SQLITE_
68e0: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c IOCAP_UNDELETABL
68f0: 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 E_WHEN_OPEN.** f
6900: 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61 lag indicate tha
6910: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 t a file cannot
6920: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 be deleted when
6930: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 open. The.** SQ
6940: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 LITE_IOCAP_IMMUT
6950: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 ABLE flag indica
6960: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c tes that the fil
6970: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d e is on.** read-
6980: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 only media and c
6990: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 annot be changed
69a0: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 even by process
69b0: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 es with.** eleva
69c0: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a ted privileges..
69d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
69e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 E_IOCAP_ATOMIC
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
6a00: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e x00000001.#defin
6a10: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6a20: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 TOMIC512
6a30: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
6a40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6a50: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 IOCAP_ATOMIC1K
6a60: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6a70: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 0000004.#define
6a80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6a90: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 MIC2K
6aa0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 0x00000008.#
6ab0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6ac0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 CAP_ATOMIC4K
6ad0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6ae0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 00010.#define SQ
6af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6b00: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C8K
6b10: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 0x00000020.#de
6b20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6b30: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 P_ATOMIC16K
6b40: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6b50: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 040.#define SQLI
6b60: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 TE_IOCAP_ATOMIC3
6b70: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2K
6b80: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 0x00000080.#defi
6b90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6ba0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 ATOMIC64K
6bb0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 0x0000010
6bc0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
6bd0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
6be0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 ND 0x
6bf0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 00000200.#define
6c00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
6c10: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 QUENTIAL
6c20: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0x00000400.
6c30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6c40: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 OCAP_UNDELETABLE
6c50: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 _WHEN_OPEN 0x00
6c60: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 000800.#define S
6c70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
6c80: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 RSAFE_OVERWRITE
6c90: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 0x00001000.#d
6ca0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
6cb0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 AP_IMMUTABLE
6cc0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
6cd0: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 2000../*.** CAPI
6ce0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 3REF: File Locki
6cf0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 ng Levels.**.**
6d00: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 SQLite uses one
6d10: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 of these integer
6d20: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
6d30: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e econd.** argumen
6d40: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 t to calls it ma
6d50: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b kes to the xLock
6d60: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 () and xUnlock()
6d70: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 methods.** of a
6d80: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 n [sqlite3_io_me
6d90: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a thods] object..*
6da0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6db0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 _LOCK_NONE
6dc0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
6dd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
6de0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
6df0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 e SQLITE_LOCK_RE
6e00: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 SERVED 2.#d
6e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
6e20: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 K_PENDING
6e30: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
6e40: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 _LOCK_EXCLUSIVE
6e50: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 4../*.** CAP
6e60: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 I3REF: Synchroni
6e70: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 zation Type Flag
6e80: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c s.**.** When SQL
6e90: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 ite invokes the
6ea0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f xSync() method o
6eb0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 f an.** [sqlite3
6ec0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
6ed0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f ect it uses a co
6ee0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 mbination of.**
6ef0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 these integer va
6f00: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f lues as the seco
6f10: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
6f20: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 ** When the SQLI
6f30: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
6f40: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 flag is used, i
6f50: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 t means that the
6f60: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 .** sync operati
6f70: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f on only needs to
6f80: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d flush data to m
6f90: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e ass storage. In
6fa0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 ode.** informati
6fb0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 on need not be f
6fc0: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c lushed. If the l
6fd0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f ower four bits o
6fe0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 f the flag.** eq
6ff0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ual SQLITE_SYNC_
7000: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 NORMAL, that mea
7010: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c ns to use normal
7020: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 fsync() semanti
7030: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f cs..** If the lo
7040: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 wer four bits eq
7050: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ual SQLITE_SYNC_
7060: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 FULL, that means
7070: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f .** to use Mac O
7080: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 S X style fullsy
7090: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 nc instead of fs
70a0: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 ync()..**.** Do
70b0: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 not confuse the
70c0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
70d0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 AL and SQLITE_SY
70e0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a NC_FULL flags.**
70f0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d with the [PRAGM
7100: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e A synchronous]=N
7110: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d ORMAL and [PRAGM
7120: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 A synchronous]=F
7130: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e ULL.** settings.
7140: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f The [synchrono
7150: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 us pragma] deter
7160: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 mines when calls
7170: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 to the.** xSync
7180: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 VFS method occu
7190: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e r and applies un
71a0: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 iformly across a
71b0: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a ll platforms..**
71c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 The SQLITE_SYNC
71d0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 _NORMAL and SQLI
71e0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 TE_SYNC_FULL fla
71f0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 gs determine how
7200: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 .** energetic or
7210: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 rigorous or for
7220: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f ceful the sync o
7230: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e perations are an
7240: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 d.** only make a
7250: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d difference on M
7260: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 ac OSX for the d
7270: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f efault SQLite co
7280: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 de..** (Third-pa
7290: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e rty VFS implemen
72a0: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c tations might al
72b0: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 so make the dist
72c0: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 inction.** betwe
72d0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e en SQLITE_SYNC_N
72e0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 ORMAL and SQLITE
72f0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 _SYNC_FULL, but
7300: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 among the.** ope
7310: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e rating systems n
7320: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 atively supporte
7330: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c d by SQLite, onl
7340: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 y Mac OSX.** car
7350: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 es about the dif
7360: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 ference.).*/.#de
7370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 fine SQLITE_SYNC
7380: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 _NORMAL 0
7390: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 x00002.#define S
73a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 QLITE_SYNC_FULL
73b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0x00003
73c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
73d0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 SYNC_DATAONLY
73e0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 0x00010../*.*
73f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
7400: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 nterface Open Fi
7410: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 le Handle.**.**
7420: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 An [sqlite3_file
7430: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 ] object represe
7440: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 nts an open file
7450: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c in the .** [sql
7460: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e ite3_vfs | OS in
7470: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 terface layer].
7480: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 Individual OS i
7490: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c nterface.** impl
74a0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c ementations will
74b0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 .** want to subc
74c0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 lass this object
74d0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 by appending ad
74e0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a ditional fields.
74f0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e ** for their own
7500: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 use. The pMeth
7510: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 ods entry is a p
7520: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
7530: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
7540: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 ods] object that
7550: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 defines methods
7560: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a for performing.
7570: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e ** I/O operation
7580: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 s on the open fi
7590: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 le..*/.typedef s
75a0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 truct sqlite3_fi
75b0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b le sqlite3_file;
75c0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
75d0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 file {. const s
75e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
75f0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f _methods *pMetho
7600: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 ds; /* Methods
7610: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 for an open file
7620: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
7630: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
7640: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 face File Virtua
7650: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 l Methods Object
7660: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c .**.** Every fil
7670: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 e opened by the
7680: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
7690: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c en] method popul
76a0: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 ates an.** [sqli
76b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
76c0: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f (or, more commo
76d0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 nly, a subclass
76e0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
76f0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 e3_file] object)
7700: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
7710: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
7720: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a f this object..*
7730: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 * This object de
7740: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 fines the method
7750: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 s used to perfor
7760: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 m various operat
7770: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 ions.** against
7780: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 the open file re
7790: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 presented by the
77a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
77b0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 object..**.** If
77c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
77d0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 s.xOpen] method
77e0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 sets the sqlite3
77f0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 _file.pMethods e
7800: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 lement .** to a
7810: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
7820: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 , then the sqlit
7830: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 e3_io_methods.xC
7840: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d lose method.** m
7850: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 ay be invoked ev
7860: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 en if the [sqlit
7870: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 e3_vfs.xOpen] re
7880: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 ported that it f
7890: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f ailed. The.** o
78a0: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 nly way to preve
78b0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c nt a call to xCl
78c0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 ose following a
78d0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f failed [sqlite3_
78e0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 vfs.xOpen].** is
78f0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 for the [sqlite
7900: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 3_vfs.xOpen] to
7910: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f set the sqlite3_
7920: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c file.pMethods el
7930: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c ement.** to NULL
7940: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
7950: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 s argument to xS
7960: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f ync may be one o
7970: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e f [SQLITE_SYNC_N
7980: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 ORMAL] or.** [SQ
7990: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e LITE_SYNC_FULL].
79a0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 The first choi
79b0: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c ce is the normal
79c0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 fsync()..** The
79d0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 second choice i
79e0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 s a Mac OS X sty
79f0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 le fullsync. Th
7a00: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 e [SQLITE_SYNC_D
7a10: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 ATAONLY].** flag
7a20: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 may be ORed in
7a30: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 to indicate that
7a40: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f only the data o
7a50: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e f the file.** an
7a60: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 d not its inode
7a70: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 needs to be sync
7a80: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e ed..**.** The in
7a90: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 teger values to
7aa0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c xLock() and xUnl
7ab0: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 ock() are one of
7ac0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
7ad0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
7ae0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 NE],.** <li> [SQ
7af0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
7b00: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
7b10: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 TE_LOCK_RESERVED
7b20: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
7b30: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d TE_LOCK_PENDING]
7b40: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 , or.** <li> [SQ
7b50: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
7b60: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a IVE]..** </ul>.*
7b70: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 * xLock() increa
7b80: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 ses the lock. xU
7b90: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 nlock() decrease
7ba0: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 s the lock..** T
7bb0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 he xCheckReserve
7bc0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 dLock() method c
7bd0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e hecks whether an
7be0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 y database conne
7bf0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 ction,.** either
7c00: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 in this process
7c10: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 or in some othe
7c20: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f r process, is ho
7c30: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 lding a RESERVED
7c40: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 ,.** PENDING, or
7c50: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 EXCLUSIVE lock
7c60: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 on the file. It
7c70: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a returns true.**
7c80: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 if such a lock
7c90: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 exists and false
7ca0: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a otherwise..**.*
7cb0: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 * The xFileContr
7cc0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 ol() method is a
7cd0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 generic interfa
7ce0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 ce that allows c
7cf0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 ustom.** VFS imp
7d00: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 lementations to
7d10: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c directly control
7d20: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 an open file us
7d30: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
7d40: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
7d50: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ()] interface.
7d60: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 The second "op"
7d70: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a argument is an.*
7d80: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 * integer opcode
7d90: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 . The third arg
7da0: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 ument is a gener
7db0: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e ic pointer inten
7dc0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 ded to.** point
7dd0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 to a structure t
7de0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 hat may contain
7df0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 arguments or spa
7e00: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a ce in which to.*
7e10: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 * write return v
7e20: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 alues. Potentia
7e30: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 l uses for xFile
7e40: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 Control() might
7e50: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 be.** functions
7e60: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 to enable blocki
7e70: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 ng locks with ti
7e80: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 meouts, to chang
7e90: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 e the.** locking
7ea0: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 strategy (for e
7eb0: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f xample to use do
7ec0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 t-file locks), t
7ed0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f o inquire.** abo
7ee0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 ut the status of
7ef0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 a lock, or to b
7f00: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 reak stale locks
7f10: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a . The SQLite.**
7f20: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 core reserves a
7f30: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 ll opcodes less
7f40: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 than 100 for its
7f50: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b own use..** A [
7f60: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 file control opc
7f70: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f odes | list of o
7f80: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 pcodes] less tha
7f90: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 n 100 is availab
7fa0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 le..** Applicati
7fb0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 ons that define
7fc0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f a custom xFileCo
7fd0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f ntrol method sho
7fe0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a uld use opcodes.
7ff0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 ** greater than
8000: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 100 to avoid con
8010: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 flicts. VFS imp
8020: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
8030: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 uld.** return [S
8040: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 QLITE_NOTFOUND]
8050: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c for file control
8060: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 opcodes that th
8070: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 ey do not.** rec
8080: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 ognize..**.** Th
8090: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 e xSectorSize()
80a0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 method returns t
80b0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f he sector size o
80c0: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 f the.** device
80d0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 that underlies t
80e0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 he file. The se
80f0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 ctor size is the
8100: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 .** minimum writ
8110: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 e that can be pe
8120: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 rformed without
8130: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 disturbing.** ot
8140: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 her bytes in the
8150: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 file. The xDev
8160: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
8170: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 cs().** method r
8180: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 eturns a bit vec
8190: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 tor describing b
81a0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a ehaviors of the.
81b0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 ** underlying de
81c0: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e vice:.**.** <ul>
81d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
81e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a _IOCAP_ATOMIC].*
81f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
8200: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a OCAP_ATOMIC512].
8210: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8220: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a IOCAP_ATOMIC1K].
8230: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8240: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a IOCAP_ATOMIC2K].
8250: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8260: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a IOCAP_ATOMIC4K].
8270: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8280: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a IOCAP_ATOMIC8K].
8290: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
82a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d IOCAP_ATOMIC16K]
82b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
82c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b _IOCAP_ATOMIC32K
82d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
82e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 E_IOCAP_ATOMIC64
82f0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
8300: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
8310: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 PEND].** <li> [S
8320: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
8330: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e ENTIAL].** </ul>
8340: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
8350: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
8360: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
8370: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
8380: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
8390: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
83a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
83b0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
83c0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
83d0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
83e0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
83f0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
8400: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
8410: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
8420: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
8430: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
8440: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
8450: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
8460: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
8470: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
8480: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
8490: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
84a0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
84b0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
84c0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
84d0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
84e0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
84f0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
8500: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
8510: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
8520: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
8530: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
8540: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
8550: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
8560: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
8570: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a to xWrite()..**
8580: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 .** If xRead() r
8590: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f eturns SQLITE_IO
85a0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 ERR_SHORT_READ i
85b0: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c t must also fill
85c0: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 .** in the unrea
85d0: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 d portions of th
85e0: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 e buffer with ze
85f0: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 ros. A VFS that
8600: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 .** fails to zer
8610: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
8620: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f ds might seem to
8630: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c work. However,
8640: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a .** failure to z
8650: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 ero-fill short r
8660: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 eads will eventu
8670: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 ally lead to.**
8680: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 database corrupt
8690: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
86a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
86b0: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 o_methods sqlite
86c0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 3_io_methods;.st
86d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
86e0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 methods {. int
86f0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 iVersion;. int
8700: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 (*xClose)(sqlite
8710: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
8720: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 (*xRead)(sqlite3
8730: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 _file*, void*, i
8740: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 nt iAmt, sqlite3
8750: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 _int64 iOfst);.
8760: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 int (*xWrite)(s
8770: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f qlite3_file*, co
8780: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 nst void*, int i
8790: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 Amt, sqlite3_int
87a0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 64 iOfst);. int
87b0: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 (*xTruncate)(sq
87c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c lite3_file*, sql
87d0: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 ite3_int64 size)
87e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 ;. int (*xSync)
87f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8800: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e int flags);. in
8810: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 t (*xFileSize)(s
8820: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
8830: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 lite3_int64 *pSi
8840: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f ze);. int (*xLo
8850: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
8860: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
8870: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 *xUnlock)(sqlite
8880: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
8890: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 int (*xCheckRes
88a0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 ervedLock)(sqlit
88b0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 e3_file*, int *p
88c0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 ResOut);. int (
88d0: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 *xFileControl)(s
88e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
88f0: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 t op, void *pArg
8900: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 );. int (*xSect
8910: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f orSize)(sqlite3_
8920: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
8930: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
8940: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f istics)(sqlite3_
8950: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 file*);. /* Met
8960: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 hods above are v
8970: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e alid for version
8980: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 1 */. int (*xS
8990: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 hmMap)(sqlite3_f
89a0: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 ile*, int iPg, i
89b0: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f nt pgsz, int, vo
89c0: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a id volatile**);.
89d0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b int (*xShmLock
89e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
89f0: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 int offset, int
8a00: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a n, int flags);.
8a10: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 void (*xShmBar
8a20: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 rier)(sqlite3_fi
8a30: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 le*);. int (*xS
8a40: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 hmUnmap)(sqlite3
8a50: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 _file*, int dele
8a60: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 teFlag);. /* Me
8a70: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
8a80: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f valid for versio
8a90: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 n 2 */. int (*x
8aa0: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 Fetch)(sqlite3_f
8ab0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
8ac0: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 t64 iOfst, int i
8ad0: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b Amt, void **pp);
8ae0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 . int (*xUnfetc
8af0: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a h)(sqlite3_file*
8b00: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
8b10: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b iOfst, void *p);
8b20: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 . /* Methods ab
8b30: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f ove are valid fo
8b40: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 r version 3 */.
8b50: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d /* Additional m
8b60: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 ethods may be ad
8b70: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
8b80: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a leases */.};../*
8b90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 .** CAPI3REF: St
8ba0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 andard File Cont
8bb0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b rol Opcodes.** K
8bc0: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 EYWORDS: {file c
8bd0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 ontrol opcodes}
8be0: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 {file control op
8bf0: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 code}.**.** Thes
8c00: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
8c10: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 nts are opcodes
8c20: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e for the xFileCon
8c30: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f trol method.** o
8c40: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 f the [sqlite3_i
8c50: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
8c60: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 t and for the [s
8c70: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
8c80: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 rol()].** interf
8c90: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ace..**.** <ul>.
8ca0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
8cb0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d FCNTL_LOCKSTATE]
8cc0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
8cd0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
8ce0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
8cf0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 for debugging.
8d00: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 This.** opcode
8d10: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 causes the xFile
8d20: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 Control method t
8d30: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 o write the curr
8d40: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 ent state of.**
8d50: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 the lock (one of
8d60: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
8d70: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 NE], [SQLITE_LOC
8d80: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 K_SHARED],.** [S
8d90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
8da0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f VED], [SQLITE_LO
8db0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 CK_PENDING], or
8dc0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
8dd0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f LUSIVE]).** into
8de0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 an integer that
8df0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 the pArg argume
8e00: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 nt points to. Th
8e10: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a is capability.**
8e20: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 is used during
8e30: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f testing and is o
8e40: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 nly available wh
8e50: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 en the SQLITE_TE
8e60: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 ST.** compile-ti
8e70: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 me option is use
8e80: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 d..**.** <li>[[S
8e90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 QLITE_FCNTL_SIZE
8ea0: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b _HINT]].** The [
8eb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a SQLITE_FCNTL_SIZ
8ec0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 E_HINT] opcode i
8ed0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 s used by SQLite
8ee0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 to give the VFS
8ef0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 .** layer a hint
8f00: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 of how large th
8f10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
8f20: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 will grow to be
8f30: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 during the.** cu
8f40: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f rrent transactio
8f50: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 n. This hint is
8f60: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 not guaranteed
8f70: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 to be accurate b
8f80: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 ut it.** is ofte
8f90: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e n close. The un
8fa0: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 derlying VFS mig
8fb0: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 ht choose to pre
8fc0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 allocate databas
8fd0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 e.** file space
8fe0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 based on this hi
8ff0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 nt in order to h
9000: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 elp writes to th
9010: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 e database.** fi
9020: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a le run faster..*
9030: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9040: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 E_FCNTL_CHUNK_SI
9050: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ZE]].** The [SQL
9060: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f ITE_FCNTL_CHUNK_
9070: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 SIZE] opcode is
9080: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 used to request
9090: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 that the VFS.**
90a0: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e extends and trun
90b0: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 cates the databa
90c0: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b se file in chunk
90d0: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 s of a size spec
90e0: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 ified.** by the
90f0: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 user. The fourth
9100: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
9110: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
9120: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a ol()] should .**
9130: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 point to an int
9140: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 eger (type int)
9150: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e containing the n
9160: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f ew chunk-size to
9170: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 use.** for the
9180: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 nominated databa
9190: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 se. Allocating d
91a0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 atabase file spa
91b0: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 ce in large.** c
91c0: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 hunks (say 1MB a
91d0: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 t a time), may r
91e0: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 educe file-syste
91f0: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 m fragmentation
9200: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 and.** improve p
9210: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f erformance on so
9220: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a me systems..**.*
9230: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
9240: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 CNTL_FILE_POINTE
9250: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 R]].** The [SQLI
9260: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
9270: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 INTER] opcode is
9280: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 used to obtain
9290: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
92a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
92b0: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 e] object associ
92c0: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 ated with a part
92d0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a icular database.
92e0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 ** connection.
92f0: 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 See the [sqlite3
9300: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
9310: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 documentation f
9320: 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c or.** additional
9330: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
9340: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
9350: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 _FCNTL_SYNC_OMIT
9360: 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 TED]].** No long
9370: 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a er in use..**.**
9380: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
9390: 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 NTL_SYNC]].** Th
93a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
93b0: 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 SYNC] opcode is
93c0: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e generated intern
93d0: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 ally by SQLite a
93e0: 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 nd.** sent to th
93f0: 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c e VFS immediatel
9400: 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 y before the xSy
9410: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 nc method is inv
9420: 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 oked on a.** dat
9430: 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 abase file descr
9440: 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 iptor. Or, if th
9450: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 e xSync method i
9460: 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a s not invoked .*
9470: 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73 * because the us
9480: 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 er has configure
9490: 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a d SQLite with .*
94a0: 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 * [PRAGMA synchr
94b0: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 onous | PRAGMA s
94c0: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 ynchronous=OFF]
94d0: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e it is invoked in
94e0: 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 place .** of th
94f0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 e xSync method.
9500: 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 In most cases, t
9510: 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d he pointer argum
9520: 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a ent passed with.
9530: 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e ** this file-con
9540: 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f trol is NULL. Ho
9550: 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 wever, if the da
9560: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 tabase file is b
9570: 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 eing synced.** a
9580: 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 s part of a mult
9590: 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 i-database commi
95a0: 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 t, the argument
95b0: 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d points to a nul-
95c0: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 terminated.** st
95d0: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ring containing
95e0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 the transactions
95f0: 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 master-journal
9600: 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 file name. VFSes
9610: 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 that .** do not
9620: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 need this signa
9630: 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c l should silentl
9640: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 y ignore this op
9650: 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f code. Applicatio
9660: 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f ns .** should no
9670: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f t call [sqlite3_
9680: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
9690: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 with this opcode
96a0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 as doing so may
96b0: 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 .** disrupt the
96c0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 operation of th
96d0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 e specialized VF
96e0: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 Ses that do requ
96f0: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 ire it. .**.**
9700: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
9710: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 TL_COMMIT_PHASET
9720: 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c WO]].** The [SQL
9730: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 ITE_FCNTL_COMMIT
9740: 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 _PHASETWO] opcod
9750: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 e is generated i
9760: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c nternally by SQL
9770: 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 ite.** and sent
9780: 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72 to the VFS after
9790: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 a transaction h
97a0: 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 as been committe
97b0: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a d immediately.**
97c0: 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 but before the
97d0: 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f database is unlo
97e0: 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 cked. VFSes that
97f0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 do not need thi
9800: 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 s signal.** shou
9810: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f ld silently igno
9820: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 re this opcode.
9830: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f Applications sho
9840: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 uld not call.**
9850: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
9860: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 ntrol()] with th
9870: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 is opcode as doi
9880: 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 ng so may disrup
9890: 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 t the .** operat
98a0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 ion of the speci
98b0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 alized VFSes tha
98c0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e t do require it.
98d0: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 .**.** <li>[[S
98e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
98f0: 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 2_AV_RETRY]].**
9900: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
9910: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 TL_WIN32_AV_RETR
9920: 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 Y] opcode is use
9930: 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 d to configure a
9940: 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 utomatic.** retr
9950: 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 y counts and int
9960: 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 ervals for certa
9970: 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 in disk I/O oper
9980: 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a ations for the.*
9990: 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 * windows [VFS]
99a0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 in order to prov
99b0: 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 ide robustness i
99c0: 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f n the presence o
99d0: 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 f.** anti-virus
99e0: 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 programs. By de
99f0: 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f fault, the windo
9a00: 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 ws VFS will retr
9a10: 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 y file read,.**
9a20: 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 file write, and
9a30: 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 file delete oper
9a40: 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 ations up to 10
9a50: 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 times, with a de
9a60: 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c lay.** of 25 mil
9a70: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 liseconds before
9a80: 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 the first retry
9a90: 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 and with the de
9aa0: 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a lay increasing.*
9ab0: 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e * by an addition
9ac0: 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e al 25 millisecon
9ad0: 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 ds with each sub
9ae0: 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 sequent retry.
9af0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 This.** opcode a
9b00: 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 llows these two
9b10: 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 values (10 retri
9b20: 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 es and 25 millis
9b30: 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 econds of delay)
9b40: 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 .** to be adjust
9b50: 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 ed. The values
9b60: 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 are changed for
9b70: 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e all database con
9b80: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 nections.** with
9b90: 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 in the same proc
9ba0: 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ess. The argume
9bb0: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 nt is a pointer
9bc0: 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 to an array of t
9bd0: 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 wo.** integers w
9be0: 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 here the first i
9bf0: 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 nteger i the new
9c00: 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 retry count and
9c10: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 the second.** i
9c20: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 nteger is the de
9c30: 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 lay. If either
9c40: 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 integer is negat
9c50: 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 ive, then the se
9c60: 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 tting.** is not
9c70: 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 changed but inst
9c80: 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 ead the prior va
9c90: 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 lue of that sett
9ca0: 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a ing is written.*
9cb0: 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 * into the array
9cc0: 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 entry, allowing
9cd0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 the current ret
9ce0: 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 ry settings to b
9cf0: 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 e.** interrogate
9d00: 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 d. The zDbName
9d10: 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e parameter is ign
9d20: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ored..**.** <li>
9d30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [[SQLITE_FCNTL_P
9d40: 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 ERSIST_WAL]].**
9d50: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
9d60: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 TL_PERSIST_WAL]
9d70: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
9d80: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 o set or query t
9d90: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 he.** persistent
9da0: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 [WAL | Write Ah
9db0: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 ead Log] setting
9dc0: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 . By default, t
9dd0: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 he auxiliary.**
9de0: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 write ahead log
9df0: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 and shared memor
9e00: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 y files used for
9e10: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e transaction con
9e20: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f trol.** are auto
9e30: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 matically delete
9e40: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 d when the lates
9e50: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 t connection to
9e60: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
9e70: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 closes. Setting
9e80: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 persistent WAL
9e90: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 mode causes thos
9ea0: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 e files to persi
9eb0: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 st after.** clos
9ec0: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 e. Persisting t
9ed0: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 he files is usef
9ee0: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 ul when other pr
9ef0: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 ocesses that do
9f00: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 not.** have writ
9f10: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 e permission on
9f20: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f the directory co
9f30: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 ntaining the dat
9f40: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a abase file want.
9f50: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 ** to read the d
9f60: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 atabase file, as
9f70: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 the WAL and sha
9f80: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 red memory files
9f90: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 must exist.** i
9fa0: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 n order for the
9fb0: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 database to be r
9fc0: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f eadable. The fo
9fd0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
9fe0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 o.** [sqlite3_fi
9ff0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f le_control()] fo
a000: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 r this opcode sh
a010: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 ould be a pointe
a020: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e r to an integer.
a030: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 .** That integer
a040: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 is 0 to disable
a050: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 persistent WAL
a060: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 mode or 1 to ena
a070: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a ble persistent.*
a080: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 * WAL mode. If
a090: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d the integer is -
a0a0: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 1, then it is ov
a0b0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 erwritten with t
a0c0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 he current.** WA
a0d0: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 L persistence se
a0e0: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 tting..**.** <li
a0f0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
a100: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
a110: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 ITE]].** ^The [S
a120: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 QLITE_FCNTL_POWE
a130: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d RSAFE_OVERWRITE]
a140: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
a150: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 to set or query
a160: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e the.** persisten
a170: 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 t "powersafe-ove
a180: 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 rwrite" or "PSOW
a190: 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 " setting. The
a1a0: 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 PSOW setting.**
a1b0: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b determines the [
a1c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 SQLITE_IOCAP_POW
a1d0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
a1e0: 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 ] bit of the.**
a1f0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
a200: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 istics methods.
a210: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
a220: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 eter to.** [sqli
a230: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
a240: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 ()] for this opc
a250: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 ode should be a
a260: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
a270: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 teger..** That i
a280: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 nteger is 0 to d
a290: 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 isable zero-dama
a2a0: 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 ge mode or 1 to
a2b0: 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 enable zero-dama
a2c0: 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 ge.** mode. If
a2d0: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d the integer is -
a2e0: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 1, then it is ov
a2f0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 erwritten with t
a300: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 he current.** ze
a310: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 ro-damage mode s
a320: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c etting..**.** <l
a330: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
a340: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 _OVERWRITE]].**
a350: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
a360: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 TL_OVERWRITE] op
a370: 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 code is invoked
a380: 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 by SQLite after
a390: 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 opening.** a wri
a3a0: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 te transaction t
a3b0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c o indicate that,
a3c0: 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f unless it is ro
a3d0: 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f lled back for so
a3e0: 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 me.** reason, th
a3f0: 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 e entire databas
a400: 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f e file will be o
a410: 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 verwritten by th
a420: 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 e current .** tr
a430: 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 ansaction. This
a440: 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 is used by VACUU
a450: 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a M operations..**
a460: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
a470: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d _FCNTL_VFSNAME]]
a480: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
a490: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 _FCNTL_VFSNAME]
a4a0: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 opcode can be us
a4b0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 ed to obtain the
a4c0: 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c names of.** all
a4d0: 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 [VFSes] in the
a4e0: 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 VFS stack. The
a4f0: 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c names are of all
a500: 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 VFS shims and t
a510: 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 he.** final bott
a520: 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 om-level VFS are
a530: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 written into me
a540: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
a550: 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f om .** [sqlite3_
a560: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 malloc()] and th
a570: 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 e result is stor
a580: 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 ed in the char*
a590: 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 variable.** that
a5a0: 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
a5b0: 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 meter of [sqlite
a5c0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
a5d0: 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 ] points to..**
a5e0: 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 The caller is re
a5f0: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 sponsible for fr
a600: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 eeing the memory
a610: 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 when done. As
a620: 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 with.** all file
a630: 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 -control actions
a640: 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 , there is no gu
a650: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 arantee that thi
a660: 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a s will actually.
a670: 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 ** do anything.
a680: 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 Callers should
a690: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 initialize the c
a6a0: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f har* variable to
a6b0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 a NULL.** point
a6c0: 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 er in case this
a6d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 file-control is
a6e0: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e not implemented.
a6f0: 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 This file-cont
a700: 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 rol.** is intend
a710: 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 ed for diagnosti
a720: 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a c use only..**.*
a730: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
a740: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a CNTL_PRAGMA]].**
a750: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 ^Whenever a [PR
a760: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 AGMA] statement
a770: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 is parsed, an [S
a780: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
a790: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e MA] .** file con
a7a0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 trol is sent to
a7b0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 the open [sqlite
a7c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 3_file] object c
a7d0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 orresponding.**
a7e0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 to the database
a7f0: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 file to which th
a800: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 e pragma stateme
a810: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 nt refers. ^The
a820: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 argument.** to t
a830: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
a840: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
a850: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 ntrol is an arra
a860: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 y of.** pointers
a870: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 to strings (cha
a880: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 r**) in which th
a890: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 e second element
a8a0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a of the array.**
a8b0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
a8c0: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 the pragma and t
a8d0: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 he third element
a8e0: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 is the argument
a8f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d to the.** pragm
a900: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 a or NULL if the
a910: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 pragma has no a
a920: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 rgument. ^The h
a930: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a andler for an.**
a940: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
a950: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 RAGMA] file cont
a960: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c rol can optional
a970: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 ly make the firs
a980: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 t element.** of
a990: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d the char** argum
a9a0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 ent point to a s
a9b0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 tring obtained f
a9c0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 rom [sqlite3_mpr
a9d0: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 intf()].** or th
a9e0: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 e equivalent and
a9f0: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c that string wil
aa00: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 l become the res
aa10: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d ult of the pragm
aa20: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f a or.** the erro
aa30: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 r message if the
aa40: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e pragma fails. ^
aa50: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 If the.** [SQLIT
aa60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
aa70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 file control ret
aa80: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 urns [SQLITE_NOT
aa90: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 FOUND], then nor
aaa0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d mal .** [PRAGMA]
aab0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 processing cont
aac0: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 inues. ^If the
aad0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
aae0: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f AGMA].** file co
aaf0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 ntrol returns [S
ab00: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 QLITE_OK], then
ab10: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d the parser assum
ab20: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 es that the.** V
ab30: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 FS has handled t
ab40: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 he PRAGMA itself
ab50: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 and the parser
ab60: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f generates a no-o
ab70: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 p.** prepared st
ab80: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c atement if resul
ab90: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c t string is NULL
aba0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e , or that return
abb0: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 s a copy.** of t
abc0: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 he result string
abd0: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 if the string i
abe0: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e s non-NULL..** ^
abf0: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 If the [SQLITE_F
ac00: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
ac10: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e e control return
ac20: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 s.** any result
ac30: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 code other than
ac40: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b [SQLITE_OK] or [
ac50: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d SQLITE_NOTFOUND]
ac60: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 , that means.**
ac70: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 that the VFS enc
ac80: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f ountered an erro
ac90: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 r while handling
aca0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e the [PRAGMA] an
acb0: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 d the.** compila
acc0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 tion of the PRAG
acd0: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e MA fails with an
ace0: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 error. ^The [S
acf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
ad00: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 MA].** file cont
ad10: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 rol occurs at th
ad20: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 e beginning of p
ad30: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 ragma statement
ad40: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a analysis and so.
ad50: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f ** it is able to
ad60: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d override built-
ad70: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 in [PRAGMA] stat
ad80: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ements..**.** <l
ad90: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
ada0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a _BUSYHANDLER]].*
adb0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
adc0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 CNTL_BUSYHANDLER
add0: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f ].** file-contro
ade0: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 l may be invoked
adf0: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 by SQLite on th
ae00: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
ae10: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c handle.** shortl
ae20: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 y after it is op
ae30: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f ened in order to
ae40: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f provide a custo
ae50: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 m VFS with acces
ae60: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e s.** to the conn
ae70: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e ections busy-han
ae80: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 dler callback. T
ae90: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f he argument is o
aea0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 f type (void **)
aeb0: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f .** - an array o
aec0: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 f two (void *) v
aed0: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 alues. The first
aee0: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c (void *) actual
aef0: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 ly points.** to
af00: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 a function of ty
af10: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 pe (int (*)(void
af20: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 *)). In order t
af30: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e o invoke the con
af40: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 nections.** busy
af50: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 -handler, this f
af60: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 unction should b
af70: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 e invoked with t
af80: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 he second (void
af90: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 *) in.** the arr
afa0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 ay as the only a
afb0: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 rgument. If it r
afc0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
afd0: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 then the operat
afe0: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 ion.** should be
aff0: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 retried. If it
b000: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 returns zero, th
b010: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f e custom VFS sho
b020: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a uld abandon the.
b030: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 ** current opera
b040: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e tion..**.** <li>
b050: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 [[SQLITE_FCNTL_T
b060: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a EMPFILENAME]].**
b070: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 ^Application ca
b080: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 n invoke the [SQ
b090: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 LITE_FCNTL_TEMPF
b0a0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f ILENAME] file-co
b0b0: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 ntrol.** to have
b0c0: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 SQLite generate
b0d0: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 a.** temporary
b0e0: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 filename using t
b0f0: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 he same algorith
b100: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 m that is follow
b110: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a ed to generate.*
b120: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 * temporary file
b130: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 names for TEMP t
b140: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 ables and other
b150: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 internal uses.
b160: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 The.** argument
b170: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 should be a char
b180: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 ** which will be
b190: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
b1a0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 filename.** wri
b1b0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 tten into memory
b1c0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
b1d0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
b1e0: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 ]. The caller s
b1f0: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 hould.** invoke
b200: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
b210: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 on the result t
b220: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 o avoid a memory
b230: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 leak..**.** <li
b240: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
b250: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 MMAP_SIZE]].** T
b260: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
b270: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 _MMAP_SIZE] file
b280: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 control is used
b290: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 to query or set
b2a0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 the.** maximum
b2b0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
b2c0: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 that will be use
b2d0: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 d for memory-map
b2e0: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 ped I/O..** The
b2f0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
b300: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 inter to a value
b310: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 of type sqlite3
b320: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 _int64 that.** i
b330: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 s an advisory ma
b340: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
b350: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c bytes in the fil
b360: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e e to memory map.
b370: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 The.** pointer
b380: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 is overwritten
b390: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c with the old val
b3a0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 ue. The limit i
b3b0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 s not changed if
b3c0: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 .** the value or
b3d0: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 iginally pointed
b3e0: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c to is negative,
b3f0: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 and so the curr
b400: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 ent limit .** ca
b410: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 n be queried by
b420: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 passing in a poi
b430: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 nter to a negati
b440: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 ve number. This
b450: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c .** file-control
b460: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 is used interna
b470: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 lly to implement
b480: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 [PRAGMA mmap_si
b490: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ze]..**.** <li>[
b4a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 [SQLITE_FCNTL_TR
b4b0: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 ACE]].** The [SQ
b4c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 LITE_FCNTL_TRACE
b4d0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 ] file control p
b4e0: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 rovides advisory
b4f0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
b500: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 to the VFS about
b510: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 what the higher
b520: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 layers of the S
b530: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 QLite stack are
b540: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 doing..** This f
b550: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 ile control is u
b560: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 sed by some VFS
b570: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 activity tracing
b580: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 [shims]..** The
b590: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a argument is a z
b5a0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
b5b0: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c tring. Higher l
b5c0: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 ayers in the.**
b5d0: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 SQLite stack may
b5e0: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e generate instan
b5f0: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 ces of this file
b600: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 control if.** t
b610: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 he [SQLITE_USE_F
b620: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 CNTL_TRACE] comp
b630: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
b640: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a is enabled..**.*
b650: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
b660: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d CNTL_HAS_MOVED]]
b670: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
b680: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d FCNTL_HAS_MOVED]
b690: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e file control in
b6a0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 terprets its arg
b6b0: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f ument as a.** po
b6c0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
b6d0: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 ger and it write
b6e0: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f s a boolean into
b6f0: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 that integer de
b700: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 pending.** on wh
b710: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
b720: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 file has been r
b730: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f enamed, moved, o
b740: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 r deleted since
b750: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 it.** was first
b760: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c opened..**.** <l
b770: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
b780: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c _WIN32_SET_HANDL
b790: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 E]].** The [SQLI
b7a0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 TE_FCNTL_WIN32_S
b7b0: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 ET_HANDLE] opcod
b7c0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 e is used for de
b7d0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a bugging. This.*
b7e0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 * opcode causes
b7f0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
b800: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 method to swap
b810: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 the file handle
b820: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 with the one.**
b830: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 pointed to by th
b840: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e e pArg argument.
b850: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 This capabilit
b860: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 y is used during
b870: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 testing.** and
b880: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 only needs to be
b890: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 supported when
b8a0: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 SQLITE_TEST is d
b8b0: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c efined..**.** <l
b8c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
b8d0: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 _WAL_BLOCK]].**
b8e0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
b8f0: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 L_WAL_BLOCK] is
b900: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 a signal to the
b910: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69 VFS layer that i
b920: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 t might.** be ad
b930: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c vantageous to bl
b940: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 ock on the next
b950: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 WAL lock if the
b960: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 lock is not imme
b970: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c diately.** avail
b980: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73 able. The WAL s
b990: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20 ubsystem issues
b9a0: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69 this signal duri
b9b0: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 ng rare.** circu
b9c0: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 mstances in orde
b9d0: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c r to fix a probl
b9e0: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79 em with priority
b9f0: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 inversion..** A
ba00: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
ba10: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 ld <em>not</em>
ba20: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f use this file-co
ba30: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ntrol..**.** <li
ba40: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
ba50: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 ZIPVFS]].** The
ba60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 [SQLITE_FCNTL_ZI
ba70: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 PVFS] opcode is
ba80: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a implemented by z
ba90: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 ipvfs only. All
baa0: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f other.** VFS sho
bab0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 uld return SQLIT
bac0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 E_NOTFOUND for t
bad0: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a his opcode..**.*
bae0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
baf0: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 CNTL_RBU]].** Th
bb00: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
bb10: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 RBU] opcode is i
bb20: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68 mplemented by th
bb30: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73 e special VFS us
bb40: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 ed by.** the RBU
bb50: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e extension only.
bb60: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 All other VFS
bb70: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 should return SQ
bb80: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f LITE_NOTFOUND fo
bb90: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 r.** this opcode
bba0: 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a . .** </ul>.*/.
bbb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
bbc0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 CNTL_LOCKSTATE
bbd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 1.#
bbe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
bbf0: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 NTL_GET_LOCKPROX
bc00: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 YFILE 2.#d
bc10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
bc20: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TL_SET_LOCKPROXY
bc30: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 FILE 3.#de
bc40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
bc50: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 L_LAST_ERRNO
bc60: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
bc70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
bc80: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 _SIZE_HINT
bc90: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 5.#defi
bca0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
bcb0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 CHUNK_SIZE
bcc0: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 6.#defin
bcd0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 e SQLITE_FCNTL_F
bce0: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 ILE_POINTER
bcf0: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 7.#define
bd00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 SQLITE_FCNTL_SY
bd10: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 NC_OMITTED
bd20: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 8.#define
bd30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
bd40: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 32_AV_RETRY
bd50: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 9.#define S
bd60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 QLITE_FCNTL_PERS
bd70: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 IST_WAL
bd80: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 10.#define SQ
bd90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 LITE_FCNTL_OVERW
bda0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 RITE
bdb0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 11.#define SQL
bdc0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d ITE_FCNTL_VFSNAM
bdd0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
bde0: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 12.#define SQLI
bdf0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 TE_FCNTL_POWERSA
be00: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 FE_OVERWRITE
be10: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 13.#define SQLIT
be20: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 E_FCNTL_PRAGMA
be30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
be40: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
be50: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c _FCNTL_BUSYHANDL
be60: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 ER 15
be70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
be80: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 FCNTL_TEMPFILENA
be90: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a ME 16.
bea0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
beb0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 CNTL_MMAP_SIZE
bec0: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 18.#
bed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
bee0: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 NTL_TRACE
bef0: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 19.#d
bf00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
bf10: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 TL_HAS_MOVED
bf20: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 20.#de
bf30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
bf40: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 L_SYNC
bf50: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 21.#def
bf60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
bf70: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f _COMMIT_PHASETWO
bf80: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 22.#defi
bf90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
bfa0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 WIN32_SET_HANDLE
bfb0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 23.#defin
bfc0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 e SQLITE_FCNTL_W
bfd0: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 AL_BLOCK
bfe0: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 24.#define
bff0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 SQLITE_FCNTL_ZI
c000: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 PVFS
c010: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 25.#define
c020: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 SQLITE_FCNTL_RBU
c030: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
c040: 20 20 20 20 32 36 0a 0a 2f 2a 20 64 65 70 72 65 26../* depre
c050: 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 cated names */.#
c060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 define SQLITE_GE
c070: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
c080: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 SQLITE_FCNT
c090: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 L_GET_LOCKPROXYF
c0a0: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 ILE.#define SQLI
c0b0: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TE_SET_LOCKPROXY
c0c0: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 FILE SQLITE
c0d0: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 _FCNTL_SET_LOCKP
c0e0: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 ROXYFILE.#define
c0f0: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 SQLITE_LAST_ERR
c100: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 NO S
c110: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 QLITE_FCNTL_LAST
c120: 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 _ERRNO.../*.** C
c130: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 API3REF: Mutex H
c140: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 andle.**.** The
c150: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 mutex module wit
c160: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e hin SQLite defin
c170: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 es [sqlite3_mute
c180: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 x] to be an.** a
c190: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 bstract type for
c1a0: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e a mutex object.
c1b0: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 The SQLite cor
c1c0: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a e never looks.**
c1d0: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c at the internal
c1e0: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
c1f0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d of an [sqlite3_m
c200: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a utex]. It only.
c210: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f ** deals with po
c220: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 inters to the [s
c230: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 qlite3_mutex] ob
c240: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 ject..**.** Mute
c250: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 xes are created
c260: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
c270: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a utex_alloc()]..*
c280: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
c290: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 sqlite3_mutex s
c2a0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f qlite3_mutex;../
c2b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
c2c0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 S Interface Obje
c2d0: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 ct.**.** An inst
c2e0: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 ance of the sqli
c2f0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 te3_vfs object d
c300: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
c310: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 face between.**
c320: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 the SQLite core
c330: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 and the underlyi
c340: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ng operating sys
c350: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a tem. The "vfs".
c360: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f ** in the name o
c370: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 f the object sta
c380: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c nds for "virtual
c390: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 file system".
c3a0: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 See.** the [VFS
c3b0: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 | VFS documentat
c3c0: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 ion] for further
c3d0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
c3e0: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 .** The value of
c3f0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 the iVersion fi
c400: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 eld is initially
c410: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 1 but may be la
c420: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 rger in.** futur
c430: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
c440: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 Lite. Additiona
c450: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 l fields may be
c460: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 appended to this
c470: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 .** object when
c480: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c the iVersion val
c490: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e ue is increased.
c4a0: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 Note that the
c4b0: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 structure.** of
c4c0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
c4d0: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 object changes i
c4e0: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f n the transactio
c4f0: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c n between.** SQL
c500: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
c510: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 9 and 3.6.0 and
c520: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e yet the iVersion
c530: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a field was not.*
c540: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a * modified..**.*
c550: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 * The szOsFile f
c560: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 ield is the size
c570: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 of the subclass
c580: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ed [sqlite3_file
c590: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 ].** structure u
c5a0: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e sed by this VFS.
c5b0: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 mxPathname is
c5c0: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 the maximum leng
c5d0: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e th of.** a pathn
c5e0: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e ame in this VFS.
c5f0: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 .**.** Registere
c600: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 d sqlite3_vfs ob
c610: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f jects are kept o
c620: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 n a linked list
c630: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 formed by.** the
c640: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 pNext pointer.
c650: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 The [sqlite3_vf
c660: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a s_register()].**
c670: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 and [sqlite3_vf
c680: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 s_unregister()]
c690: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 interfaces manag
c6a0: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 e this list.** i
c6b0: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 n a thread-safe
c6c0: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 way. The [sqlit
c6d0: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 e3_vfs_find()] i
c6e0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 nterface.** sear
c6f0: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 ches the list.
c700: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c Neither the appl
c710: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 ication code nor
c720: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c the VFS.** impl
c730: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c ementation shoul
c740: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 d use the pNext
c750: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 pointer..**.** T
c760: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 he pNext field i
c770: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 s the only field
c780: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f in the sqlite3_
c790: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 vfs.** structure
c7a0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
c7b0: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 l ever modify.
c7c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 SQLite will only
c7d0: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f access.** or mo
c7e0: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 dify this field
c7f0: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 while holding a
c800: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 particular stati
c810: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 c mutex..** The
c820: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
c830: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 ld never modify
c840: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 anything within
c850: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a the sqlite3_vfs.
c860: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 ** object once t
c870: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 he object has be
c880: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a en registered..*
c890: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 *.** The zName f
c8a0: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e ield holds the n
c8b0: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d ame of the VFS m
c8c0: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 odule. The name
c8d0: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 must.** be uniq
c8e0: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 ue across all VF
c8f0: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a S modules..**.**
c900: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 [[sqlite3_vfs.x
c910: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 Open]].** ^SQLit
c920: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 e guarantees tha
c930: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 t the zFilename
c940: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
c950: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 en.** is either
c960: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f a NULL pointer o
c970: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 r string obtaine
c980: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 d.** from xFullP
c990: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 athname() with a
c9a0: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 n optional suffi
c9b0: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 x added..** ^If
c9c0: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 a suffix is adde
c9d0: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 d to the zFilena
c9e0: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 me parameter, it
c9f0: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 will.** consist
ca00: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 of a single "-"
ca10: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f character follo
ca20: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 wed by no more t
ca30: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e han.** 11 alphan
ca40: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d umeric and/or "-
ca50: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a " characters..**
ca60: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 ^SQLite further
ca70: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
ca80: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 .** the string w
ca90: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 ill be valid and
caa0: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c unchanged until
cab0: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 xClose() is.**
cac0: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 called. Because
cad0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 of the previous
cae0: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 sentence,.** the
caf0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
cb00: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 can safely store
cb10: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
cb20: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 e.** filename if
cb30: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d it needs to rem
cb40: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 ember the filena
cb50: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 me for some reas
cb60: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 on..** If the zF
cb70: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
cb80: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 r to xOpen is a
cb90: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
cba0: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 n xOpen.** must
cbb0: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 invent its own t
cbc0: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f emporary name fo
cbd0: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 r the file. ^Wh
cbe0: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 enever the .** x
cbf0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
cc00: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 er is NULL it wi
cc10: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 ll also be the c
cc20: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ase that the.**
cc30: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
cc40: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 will include [SQ
cc50: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
cc60: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 ONCLOSE]..**.**
cc70: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
cc80: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e nt to xOpen() in
cc90: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 cludes all bits
cca0: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c set in.** the fl
ccb0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ags argument to
ccc0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
ccd0: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c ()]. Or if [sql
cce0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 ite3_open()].**
ccf0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e or [sqlite3_open
cd00: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 16()] is used, t
cd10: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 hen flags includ
cd20: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b es at least.** [
cd30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
cd40: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 WRITE] | [SQLITE
cd50: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a _OPEN_CREATE]. .
cd60: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 ** If xOpen() op
cd70: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d ens a file read-
cd80: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 only then it set
cd90: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a s *pOutFlags to.
cda0: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 ** include [SQLI
cdb0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
cdc0: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 ]. Other bits i
cdd0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 n *pOutFlags may
cde0: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e be set..**.** ^
cdf0: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 (SQLite will als
ce00: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 o add one of the
ce10: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 following flags
ce20: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a to the xOpen().
ce30: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 ** call, dependi
ce40: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 ng on the object
ce50: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a being opened:.*
ce60: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
ce70: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
ce80: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e MAIN_DB].** <li>
ce90: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
cea0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 AIN_JOURNAL].**
ceb0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
cec0: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c EN_TEMP_DB].** <
ced0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
cee0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a N_TEMP_JOURNAL].
cef0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
cf00: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f _OPEN_TRANSIENT_
cf10: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
cf20: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 LITE_OPEN_SUBJOU
cf30: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
cf40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 SQLITE_OPEN_MAST
cf50: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c ER_JOURNAL].** <
cf60: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
cf70: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 N_WAL].** </ul>)
cf80: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 ^.**.** The file
cf90: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 I/O implementat
cfa0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 ion can use the
cfb0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 object type flag
cfc0: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 s to.** change t
cfd0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 he way it deals
cfe0: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 with files. For
cff0: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 example, an app
d000: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 lication.** that
d010: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 does not care a
d020: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 bout crash recov
d030: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 ery or rollback
d040: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 might make.** th
d050: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 e open of a jour
d060: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 nal file a no-op
d070: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 . Writes to thi
d080: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a s journal would.
d090: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 ** also be no-op
d0a0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d s, and any attem
d0b0: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a pt to read the j
d0c0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 ournal would ret
d0d0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f urn.** SQLITE_IO
d0e0: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 ERR. Or the imp
d0f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 lementation migh
d100: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 t recognize that
d110: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 a database.** f
d120: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e ile will be doin
d130: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 g page-aligned s
d140: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 ector reads and
d150: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 writes in a rand
d160: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 om.** order and
d170: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 set up its I/O s
d180: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 ubsystem accordi
d190: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 ngly..**.** SQLi
d1a0: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 te might also ad
d1b0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c d one of the fol
d1c0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 lowing flags to
d1d0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 the xOpen method
d1e0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
d1f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 <li> [SQLITE_OPE
d200: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
d210: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
d220: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d _OPEN_EXCLUSIVE]
d230: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
d240: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
d250: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 _DELETEONCLOSE]
d260: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 flag means the f
d270: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a ile should be.**
d280: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 deleted when it
d290: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 is closed. ^Th
d2a0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 e [SQLITE_OPEN_D
d2b0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a ELETEONCLOSE].**
d2c0: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 will be set for
d2d0: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 TEMP databases
d2e0: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 and their journa
d2f0: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a ls, transient.**
d300: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 databases, and
d310: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a subjournals..**.
d320: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
d330: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 OPEN_EXCLUSIVE]
d340: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 flag is always u
d350: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 sed in conjuncti
d360: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b on.** with the [
d370: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
d380: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 TE] flag, which
d390: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c are both directl
d3a0: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 y.** analogous t
d3b0: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 o the O_EXCL and
d3c0: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f O_CREAT flags o
d3d0: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e f the POSIX open
d3e0: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 ().** API. The
d3f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
d400: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e USIVE flag, when
d410: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 paired with the
d420: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e .** SQLITE_OPEN
d430: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 _CREATE, is used
d440: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
d450: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c t file should al
d460: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 ways.** be creat
d470: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 ed, and that it
d480: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 is an error if i
d490: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 t already exists
d4a0: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f ..** It is <i>no
d4b0: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e t</i> used to in
d4c0: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 dicate the file
d4d0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 should be opened
d4e0: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 .** for exclusi
d4f0: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a ve access..**.**
d500: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 ^At least szOsF
d510: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d ile bytes of mem
d520: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 ory are allocate
d530: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 d by SQLite.** t
d540: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c o hold the [sql
d550: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 ite3_file] struc
d560: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 ture passed as t
d570: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 he third.** argu
d580: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 ment to xOpen.
d590: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 The xOpen method
d5a0: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 does not have t
d5b0: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 o.** allocate th
d5c0: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 e structure; it
d5d0: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c should just fill
d5e0: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 it in. Note th
d5f0: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 at.** the xOpen
d600: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 method must set
d610: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 the sqlite3_file
d620: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 .pMethods to eit
d630: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b her.** a valid [
d640: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
d650: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f ds] object or to
d660: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 NULL. xOpen mu
d670: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 st do.** this ev
d680: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 en if the open f
d690: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 ails. SQLite ex
d6a0: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 pects that the s
d6b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 qlite3_file.pMet
d6c0: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 hods.** element
d6d0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 will be valid af
d6e0: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e ter xOpen return
d6f0: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 s regardless of
d700: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f the success.** o
d710: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 r failure of the
d720: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a xOpen call..**.
d730: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 ** [[sqlite3_vfs
d740: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 .xAccess]].** ^T
d750: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
d760: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d t to xAccess() m
d770: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 ay be [SQLITE_AC
d780: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 CESS_EXISTS].**
d790: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 to test for the
d7a0: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 existence of a f
d7b0: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f ile, or [SQLITE_
d7c0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
d7d0: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 ] to.** test whe
d7e0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 ther a file is r
d7f0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 eadable and writ
d800: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 able, or [SQLITE
d810: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a _ACCESS_READ].**
d820: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 to test whether
d830: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 a file is at le
d840: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 ast readable.
d850: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 The file can be
d860: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a a.** directory..
d870: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 **.** ^SQLite wi
d880: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 ll always alloca
d890: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 te at least mxPa
d8a0: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 thname+1 bytes f
d8b0: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 or the.** output
d8c0: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 buffer xFullPat
d8d0: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 hname. The exac
d8e0: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 t size of the ou
d8f0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
d900: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 s also passed as
d910: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 a parameter to
d920: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 both methods. I
d930: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
d940: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 fer.** is not la
d950: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c rge enough, [SQL
d960: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 ITE_CANTOPEN] sh
d970: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
d980: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a . Since this is.
d990: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 ** handled as a
d9a0: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 fatal error by S
d9b0: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 QLite, vfs imple
d9c0: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c mentations shoul
d9d0: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f d endeavor.** to
d9e0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 prevent this by
d9f0: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e setting mxPathn
da00: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 ame to a suffici
da10: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 ently large valu
da20: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 e..**.** The xRa
da30: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 ndomness(), xSle
da40: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 ep(), xCurrentTi
da50: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 me(), and xCurre
da60: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a ntTimeInt64().**
da70: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
da80: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 not strictly a p
da90: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 art of the files
daa0: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 ystem, but they
dab0: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 are.** included
dac0: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 in the VFS struc
dad0: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 ture for complet
dae0: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 eness..** The xR
daf0: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 andomness() func
db00: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f tion attempts to
db10: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 return nBytes b
db20: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d ytes.** of good-
db30: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 quality randomne
db40: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 ss into zOut. T
db50: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
db60: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c is.** the actual
db70: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
db80: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f of randomness o
db90: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 btained..** The
dba0: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 xSleep() method
dbb0: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 causes the calli
dbc0: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 ng thread to sle
dbd0: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 ep for at.** lea
dbe0: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 st the number of
dbf0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 microseconds gi
dc00: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 ven. ^The xCurr
dc10: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 entTime().** met
dc20: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 hod returns a Ju
dc30: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 lian Day Number
dc40: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 for the current
dc50: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 date and time as
dc60: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 .** a floating p
dc70: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e oint value..** ^
dc80: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 The xCurrentTime
dc90: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 Int64() method r
dca0: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e eturns, as an in
dcb0: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 teger, the Julia
dcc0: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 n.** Day Number
dcd0: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 multiplied by 86
dce0: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 400000 (the numb
dcf0: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
dd00: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 ds in .** a 24-h
dd10: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e our day). .** ^
dd20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 SQLite will use
dd30: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 the xCurrentTime
dd40: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 Int64() method t
dd50: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e o get the curren
dd60: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 t.** date and ti
dd70: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f me if that metho
dd80: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 d is available (
dd90: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 if iVersion is 2
dda0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 or .** greater
ddb0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e and the function
ddc0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
ddd0: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 NULL) and will f
dde0: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 all back.** to x
ddf0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 CurrentTime() if
de00: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 xCurrentTimeInt
de10: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 64() is unavaila
de20: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ble..**.** ^The
de30: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 xSetSystemCall()
de40: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c , xGetSystemCall
de50: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 (), and xNestSys
de60: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 temCall() interf
de70: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 aces.** are not
de80: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 used by the SQLi
de90: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 te core. These
dea0: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 optional interfa
deb0: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 ces are provided
dec0: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 .** by some VFSe
ded0: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 s to facilitate
dee0: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 testing of the V
def0: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 FS code. By over
df00: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 riding .** syste
df10: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e m calls with fun
df20: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 ctions under its
df30: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 control, a test
df40: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 program can.**
df50: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 simulate faults
df60: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 and error condit
df70: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 ions that would
df80: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 otherwise be dif
df90: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 ficult.** or imp
dfa0: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 ossible to induc
dfb0: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 e. The set of s
dfc0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 ystem calls that
dfd0: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 can be overridd
dfe0: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f en.** varies fro
dff0: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f m one VFS to ano
e000: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f ther, and from o
e010: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 ne version of th
e020: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 e same VFS to th
e030: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c e.** next. Appl
e040: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 ications that us
e050: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 e these interfac
e060: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 es must be prepa
e070: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f red for any.** o
e080: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 r all of these i
e090: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 nterfaces to be
e0a0: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 NULL or for thei
e0b0: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 r behavior to ch
e0c0: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 ange.** from one
e0d0: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 release to the
e0e0: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 next. Applicati
e0f0: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 ons must not att
e100: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a empt to access.*
e110: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d * any of these m
e120: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 ethods if the iV
e130: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 ersion of the VF
e140: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 S is less than 3
e150: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
e160: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 uct sqlite3_vfs
e170: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 sqlite3_vfs;.typ
e180: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 edef void (*sqli
e190: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 te3_syscall_ptr)
e1a0: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 (void);.struct s
e1b0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 qlite3_vfs {. i
e1c0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 nt iVersion;
e1d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 /* Struc
e1e0: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d ture version num
e1f0: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 ber (currently 3
e200: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 ) */. int szOsF
e210: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 ile;
e220: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c /* Size of subcl
e230: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 assed sqlite3_fi
e240: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 le */. int mxPa
e250: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 thname;
e260: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 /* Maximum file
e270: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 pathname length
e280: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 */. sqlite3_vf
e290: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f s *pNext; /
e2a0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 * Next registere
e2b0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 d VFS */. const
e2c0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 char *zName;
e2d0: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
e2e0: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 his virtual file
e2f0: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 system */. voi
e300: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
e310: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 /* Pointer
e320: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d to application-
e330: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f specific data */
e340: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 . int (*xOpen)(
e350: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
e360: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
e370: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a sqlite3_file*,.
e380: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 i
e390: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 nt flags, int *p
e3a0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 OutFlags);. int
e3b0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 (*xDelete)(sqli
e3c0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
e3d0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
e3e0: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 syncDir);. int
e3f0: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 (*xAccess)(sqli
e400: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
e410: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
e420: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 flags, int *pRe
e430: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sOut);. int (*x
e440: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 FullPathname)(sq
e450: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
e460: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 t char *zName, i
e470: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a nt nOut, char *z
e480: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a Out);. void *(*
e490: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 xDlOpen)(sqlite3
e4a0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
e4b0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 r *zFilename);.
e4c0: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 void (*xDlError
e4d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e4e0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 int nByte, char
e4f0: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 *zErrMsg);. voi
e500: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 d (*(*xDlSym)(sq
e510: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a lite3_vfs*,void*
e520: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 , const char *zS
e530: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 ymbol))(void);.
e540: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 void (*xDlClose
e550: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e560: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a void*);. int (*
e570: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c xRandomness)(sql
e580: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e ite3_vfs*, int n
e590: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 Byte, char *zOut
e5a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 );. int (*xSlee
e5b0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c p)(sqlite3_vfs*,
e5c0: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 int microsecond
e5d0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 s);. int (*xCur
e5e0: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 rentTime)(sqlite
e5f0: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3_vfs*, double*)
e600: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 ;. int (*xGetLa
e610: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 stError)(sqlite3
e620: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 _vfs*, int, char
e630: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 *);. /*. ** T
e640: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
e650: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 are in version
e660: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 1 of the sqlite_
e670: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 vfs object. **
e680: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f definition. Tho
e690: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 se that follow a
e6a0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 re added in vers
e6b0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 ion 2 or later.
e6c0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 */. int (*xCur
e6d0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 rentTimeInt64)(s
e6e0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c qlite3_vfs*, sql
e6f0: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 ite3_int64*);.
e700: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
e710: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
e720: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 versions 1 and
e730: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 2 of the sqlite_
e740: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a vfs object.. **
e750: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 Those below are
e760: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 for version 3 a
e770: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f nd greater.. */
e780: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 . int (*xSetSys
e790: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 temCall)(sqlite3
e7a0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
e7b0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 r *zName, sqlite
e7c0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 3_syscall_ptr);.
e7d0: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c sqlite3_syscal
e7e0: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 l_ptr (*xGetSyst
e7f0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f emCall)(sqlite3_
e800: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
e810: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 *zName);. cons
e820: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 t char *(*xNextS
e830: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 ystemCall)(sqlit
e840: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
e850: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f har *zName);. /
e860: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
e870: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
e880: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 versions 1 throu
e890: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 gh 3 of the sqli
e8a0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 te_vfs object..
e8b0: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d ** New fields m
e8c0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 ay be appended i
e8d0: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e n figure version
e8e0: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e s. The iVersion
e8f0: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c . ** value will
e900: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 increment whene
e910: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 ver this happens
e920: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a . . */.};../*.*
e930: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 * CAPI3REF: Flag
e940: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 s for the xAcces
e950: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a s VFS method.**.
e960: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 ** These integer
e970: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 constants can b
e980: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 e used as the th
e990: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
e9a0: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 .** the xAccess
e9b0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 method of an [sq
e9c0: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
e9d0: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 t. They determi
e9e0: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 ne.** what kind
e9f0: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 of permissions t
ea00: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
ea10: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 d is looking for
ea20: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 ..** With SQLITE
ea30: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 _ACCESS_EXISTS,
ea40: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
ea50: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 od.** simply che
ea60: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
ea70: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 file exists..**
ea80: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 With SQLITE_ACCE
ea90: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 SS_READWRITE, th
eaa0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
eab0: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 .** checks wheth
eac0: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 er the named dir
ead0: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 ectory is both r
eae0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 eadable and writ
eaf0: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 able.** (in othe
eb00: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 r words, if file
eb10: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 s can be added,
eb20: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e removed, and ren
eb30: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 amed within.** t
eb40: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a he directory)..*
eb50: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 * The SQLITE_ACC
eb60: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f ESS_READWRITE co
eb70: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e nstant is curren
eb80: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 tly used only by
eb90: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 the.** [temp_st
eba0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
ebb0: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 agma], though th
ebc0: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 is could change
ebd0: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 in a future.** r
ebe0: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
ebf0: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 ..** With SQLITE
ec00: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 _ACCESS_READ, th
ec10: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
ec20: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 .** checks wheth
ec30: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 er the file is r
ec40: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 eadable. The SQ
ec50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
ec60: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 constant is.**
ec70: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 currently unused
ec80: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 , though it migh
ec90: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 t be used in a f
eca0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 uture release of
ecb0: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 .** SQLite..*/.#
ecc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
ecd0: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 CESS_EXISTS 0
ece0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
ecf0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
ed00: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 1 /* Used by
ed10: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 PRAGMA temp_stor
ed20: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 e_directory */.#
ed30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
ed40: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 CESS_READ 2
ed50: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a /* Unused */.
ed60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
ed70: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 Flags for the x
ed80: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 ShmLock VFS meth
ed90: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 od.**.** These i
eda0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
edb0: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 define the vari
edc0: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 ous locking oper
edd0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 ations.** allowe
ede0: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 d by the xShmLoc
edf0: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c k method of [sql
ee00: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
ee10: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 . The.** follow
ee20: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 ing are the only
ee30: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 legal combinati
ee40: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 ons of flags to
ee50: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 the.** xShmLock
ee60: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 method:.**.** <u
ee70: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 l>.** <li> SQLI
ee80: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 TE_SHM_LOCK | SQ
ee90: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a LITE_SHM_SHARED.
eea0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
eeb0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 SHM_LOCK | SQLIT
eec0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a E_SHM_EXCLUSIVE.
eed0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
eee0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c SHM_UNLOCK | SQL
eef0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a ITE_SHM_SHARED.*
ef00: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
ef10: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 HM_UNLOCK | SQLI
ef20: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
ef30: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
ef40: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 When unlocking,
ef50: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 the same SHARED
ef60: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 or EXCLUSIVE fla
ef70: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 g must be suppli
ef80: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 ed as.** was giv
ef90: 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 en on the corres
efa0: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a ponding lock. .
efb0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f **.** The xShmLo
efc0: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 ck method can tr
efd0: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e ansition between
efe0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 unlocked and SH
eff0: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 ARED or.** betwe
f000: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 en unlocked and
f010: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 EXCLUSIVE. It c
f020: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e annot transition
f030: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a between SHARED.
f040: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 ** and EXCLUSIVE
f050: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
f060: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 ITE_SHM_UNLOCK
f070: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
f080: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 QLITE_SHM_LOCK
f090: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
f0a0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 SQLITE_SHM_SHAR
f0b0: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 ED 4.#defi
f0c0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 ne SQLITE_SHM_EX
f0d0: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a CLUSIVE 8../*
f0e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 .** CAPI3REF: Ma
f0f0: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 ximum xShmLock i
f100: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ndex.**.** The x
f110: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f ShmLock method o
f120: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 n [sqlite3_io_me
f130: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 thods] may use v
f140: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e alues.** between
f150: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 0 and this uppe
f160: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 r bound as its "
f170: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 offset" argument
f180: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 ..** The SQLite
f190: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 core will never
f1a0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 attempt to acqui
f1b0: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a re or release a.
f1c0: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 ** lock outside
f1d0: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f of this range.*/
f1e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
f1f0: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 SHM_NLOCK
f200: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 8.../*.** CAPI3
f210: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 REF: Initialize
f220: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 The SQLite Libra
f230: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ry.**.** ^The sq
f240: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f250: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 () routine initi
f260: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 alizes the.** SQ
f270: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e Lite library. ^
f280: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 The sqlite3_shut
f290: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a down() routine.*
f2a0: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e * deallocates an
f2b0: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 y resources that
f2c0: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 were allocated
f2d0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 by sqlite3_initi
f2e0: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 alize()..** Thes
f2f0: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 e routines are d
f300: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 esigned to aid i
f310: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 n process initia
f320: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 lization and.**
f330: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 shutdown on embe
f340: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 dded systems. W
f350: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 orkstation appli
f360: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a cations using.**
f370: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 SQLite normally
f380: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 do not need to
f390: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 invoke either of
f3a0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
f3b0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f .**.** A call to
f3c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
f3d0: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 ize() is an "eff
f3e0: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 ective" call if
f3f0: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 it is.** the fir
f400: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f st time sqlite3_
f410: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
f420: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 invoked during t
f430: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a he lifetime of.*
f440: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f * the process, o
f450: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 r if it is the f
f460: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 irst time sqlite
f470: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
f480: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c s invoked.** fol
f490: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f lowing a call to
f4a0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
f4b0: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 n(). ^(Only an
f4c0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a effective call.*
f4d0: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 * of sqlite3_ini
f4e0: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 tialize() does a
f4f0: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ny initializatio
f500: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 n. All other ca
f510: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c lls.** are harml
f520: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a ess no-ops.)^.**
f530: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 .** A call to sq
f540: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f550: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 is an "effectiv
f560: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 e" call if it is
f570: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 the first.** ca
f580: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
f590: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 utdown() since t
f5a0: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f he last sqlite3_
f5b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e initialize(). ^
f5c0: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 (Only.** an effe
f5d0: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 ctive call to sq
f5e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f5f0: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 does any deinit
f600: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 ialization..** A
f610: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 ll other valid c
f620: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
f630: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 shutdown() are h
f640: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 armless no-ops.)
f650: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ^.**.** The sqli
f660: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
f670: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 interface is th
f680: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 readsafe, but sq
f690: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f6a0: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 .** is not. The
f6b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
f6c0: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 n() interface mu
f6d0: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 st only be calle
f6e0: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 d from a.** sing
f6f0: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 le thread. All
f700: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 open [database c
f710: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 onnections] must
f720: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 be closed and a
f730: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 ll.** other SQLi
f740: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 te resources mus
f750: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 t be deallocated
f760: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 prior to invoki
f770: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 ng.** sqlite3_sh
f780: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 utdown()..**.**
f790: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e Among other thin
f7a0: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 gs, ^sqlite3_ini
f7b0: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 tialize() will i
f7c0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
f7d0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d _os_init(). Sim
f7e0: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 ilarly, ^sqlite3
f7f0: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 _shutdown().** w
f800: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 ill invoke sqlit
f810: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a e3_os_end()..**.
f820: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
f830: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
f840: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 tine returns [SQ
f850: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
f860: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 ess..** ^If for
f870: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c some reason, sql
f880: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
f890: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 ) is unable to i
f8a0: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 nitialize.** the
f8b0: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 library (perhap
f8c0: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 s it is unable t
f8d0: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 o allocate a nee
f8e0: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 ded resource suc
f8f0: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 h.** as a mutex)
f900: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b it returns an [
f910: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 error code] othe
f920: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f r than [SQLITE_O
f930: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 K]..**.** ^The s
f940: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
f950: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 e() routine is c
f960: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 alled internally
f970: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a by many other.*
f980: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 * SQLite interfa
f990: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 ces so that an a
f9a0: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c pplication usual
f9b0: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ly does not need
f9c0: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 to.** invoke sq
f9d0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f9e0: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f () directly. Fo
f9f0: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 r example, [sqli
fa00: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 te3_open()].** c
fa10: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 alls sqlite3_ini
fa20: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 tialize() so the
fa30: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 SQLite library
fa40: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 will be automati
fa50: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c cally.** initial
fa60: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 ized when [sqlit
fa70: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 e3_open()] is ca
fa80: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e lled if it has n
fa90: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 ot be initialize
faa0: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e d.** already. ^
fab0: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 However, if SQLi
fac0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
fad0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
fae0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a OMIT_AUTOINIT].*
faf0: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f * compile-time o
fb00: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ption, then the
fb10: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 automatic calls
fb20: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 to sqlite3_initi
fb30: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f alize().** are o
fb40: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 mitted and the a
fb50: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
fb60: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 call sqlite3_ini
fb70: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 tialize() direct
fb80: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 ly.** prior to u
fb90: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 sing any other S
fba0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
fbb0: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f For maximum po
fbc0: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 rtability,.** it
fbd0: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
fbe0: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
fbf0: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 s always invoke
fc00: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
fc10: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 ze().** directly
fc20: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 prior to using
fc30: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 any other SQLite
fc40: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 interface. Fut
fc50: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 ure releases.**
fc60: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 of SQLite may re
fc70: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 quire this. In
fc80: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
fc90: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 behavior exhibi
fca0: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 ted.** when SQLi
fcb0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
fcc0: 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 ith [SQLITE_OMIT
fcd0: 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 _AUTOINIT] might
fce0: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 become the.** d
fcf0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 efault behavior
fd00: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 in some future r
fd10: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
fd20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
fd30: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f te3_os_init() ro
fd40: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 utine does opera
fd50: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 ting-system spec
fd60: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 ific.** initiali
fd70: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 zation of the SQ
fd80: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 Lite library. T
fd90: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e he sqlite3_os_en
fda0: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 d().** routine u
fdb0: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 ndoes the effect
fdc0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 of sqlite3_os_i
fdd0: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 nit(). Typical
fde0: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d tasks.** perform
fdf0: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 ed by these rout
fe00: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c ines include all
fe10: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c ocation or deall
fe20: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 ocation.** of st
fe30: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 atic resources,
fe40: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f initialization o
fe50: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c f global variabl
fe60: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 es,.** setting u
fe70: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c p a default [sql
fe80: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 ite3_vfs] module
fe90: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a , or setting up.
fea0: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e ** a default con
feb0: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 figuration using
fec0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
fed0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 ()]..**.** The a
fee0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
fef0: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 d never invoke e
ff00: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 ither sqlite3_os
ff10: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 _init().** or sq
ff20: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 lite3_os_end() d
ff30: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 irectly. The ap
ff40: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
ff50: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 only invoke.**
ff60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
ff70: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 ze() and sqlite3
ff80: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 _shutdown(). Th
ff90: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 e sqlite3_os_ini
ffa0: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 t().** interface
ffb0: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d is called autom
ffc0: 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 atically by sqli
ffd0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
ffe0: 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f and.** sqlite3_
fff0: 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c os_end() is call
10000 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 ed by sqlite3_sh
10010 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f utdown(). Appro
10020 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d priate.** implem
10030 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 entations for sq
10040 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
10050 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 and sqlite3_os_e
10060 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c nd().** are buil
10070 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 t into SQLite wh
10080 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 en it is compile
10090 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 d for Unix, Wind
100a0 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a ows, or OS/2..**
100b0 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 When [custom bu
100c0 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 ilds | built for
100d0 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 other platforms
100e0 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 ].** (using the
100f0 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 [SQLITE_OS_OTHER
10100 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =1] compile-time
10110 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 .** option) the
10120 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
10130 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 supply a suitab
10140 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
10150 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 n for.** sqlite3
10160 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 _os_init() and s
10170 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e qlite3_os_end().
10180 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e An application
10190 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 -supplied.** imp
101a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
101b0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
101c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 or sqlite3_os_e
101d0 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 nd().** must ret
101e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
101f0 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 on success and s
10200 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 ome other [error
10210 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 code] upon.** f
10220 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 ailure..*/.SQLIT
10230 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
10240 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
10250 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 _initialize(void
10260 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
10270 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
10280 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
10290 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f n(void);.SQLITE_
102a0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
102b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f TDCALL sqlite3_o
102c0 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 s_init(void);.SQ
102d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
102e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
102f0 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 te3_os_end(void)
10300 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
10310 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 F: Configuring T
10320 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
10330 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 y.**.** The sqli
10340 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 te3_config() int
10350 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
10360 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f o make global co
10370 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 nfiguration.** c
10380 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 hanges to SQLite
10390 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e in order to tun
103a0 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 e SQLite to the
103b0 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f specific needs o
103c0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 f.** the applica
103d0 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 tion. The defau
103e0 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e lt configuration
103f0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
10400 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c for most.** appl
10410 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 ications and so
10420 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
10430 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 usually not nece
10440 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a ssary. It is.**
10450 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 provided to sup
10460 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 port rare applic
10470 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 ations with unus
10480 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ual needs..**.**
10490 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
104a0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
104b0 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 is not threadsaf
104c0 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 e. The applicat
104d0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 ion.** must insu
104e0 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 re that no other
104f0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
10500 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 es are invoked b
10510 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 y other.** threa
10520 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 ds while sqlite3
10530 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e _config() is run
10540 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f ning. Furthermo
10550 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 re, sqlite3_conf
10560 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 ig().** may only
10570 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f be invoked prio
10580 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 r to library ini
10590 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e tialization usin
105a0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e g.** [sqlite3_in
105b0 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 itialize()] or a
105c0 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 fter shutdown by
105d0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
105e0 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 wn()]..** ^If sq
105f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
10600 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b s called after [
10610 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
10620 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 ze()] and before
10630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 .** [sqlite3_shu
10640 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 tdown()] then it
10650 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c will return SQL
10660 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e ITE_MISUSE..** N
10670 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 ote, however, th
10680 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 at ^sqlite3_conf
10690 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c ig() can be call
106a0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
106b0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
106c0 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 ion of an applic
106d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 ation-defined [s
106e0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
106f0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 ]..**.** The fir
10700 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
10710 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
10720 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a is an integer.**
10730 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 [configuration
10740 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 option] that det
10750 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 ermines.** what
10760 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 property of SQLi
10770 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 te is to be conf
10780 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 igured. Subsequ
10790 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a ent arguments.**
107a0 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 vary depending
107b0 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 on the [configur
107c0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a ation option].**
107d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
107e0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 gument..**.** ^W
107f0 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 hen a configurat
10800 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 ion option is se
10810 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 t, sqlite3_confi
10820 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c g() returns [SQL
10830 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 ITE_OK]..** ^If
10840 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e the option is un
10850 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 known or SQLite
10860 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 is unable to set
10870 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 the option.** t
10880 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 hen this routine
10890 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a returns a non-z
108a0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ero [error code]
108b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
108c0 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c int SQLITE_CDECL
108d0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
108e0 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a int, ...);../*.*
108f0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
10900 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 igure database c
10910 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 onnections.** ME
10920 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
10930 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
10940 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 db_config() inte
10950 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
10960 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 make configurat
10970 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ion.** changes t
10980 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f o a [database co
10990 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 nnection]. The
109a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d interface is sim
109b0 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 ilar to.** [sqli
109c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 te3_config()] ex
109d0 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 cept that the ch
109e0 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 anges apply to a
109f0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 single.** [data
10a00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
10a10 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 (specified in t
10a20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
10a30 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 t)..**.** The se
10a40 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
10a50 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
10a60 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 ig(D,V,...) is
10a70 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 the.** [SQLITE_D
10a80 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
10a90 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f E | configuratio
10aa0 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 n verb] - an int
10ab0 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 eger code .** th
10ac0 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 at indicates wha
10ad0 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 t aspect of the
10ae0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
10af0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 tion] is being c
10b00 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 onfigured..** Su
10b10 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e bsequent argumen
10b20 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e ts vary dependin
10b30 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 g on the configu
10b40 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a ration verb..**.
10b50 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c ** ^Calls to sql
10b60 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
10b70 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f return SQLITE_O
10b80 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 K if and only if
10b90 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 .** the call is
10ba0 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 considered succe
10bb0 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ssful..*/.SQLITE
10bc0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
10bd0 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 64 62 CDECL sqlite3_db
10be0 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a _config(sqlite3*
10bf0 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a , int op, ...);.
10c00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
10c10 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 Memory Allocati
10c20 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a on Routines.**.*
10c30 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
10c40 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 this object def
10c50 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 ines the interfa
10c60 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 ce between SQLit
10c70 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 e.** and low-lev
10c80 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 el memory alloca
10c90 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a tion routines..*
10ca0 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 *.** This object
10cb0 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 is used in only
10cc0 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 one place in th
10cd0 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 e SQLite interfa
10ce0 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 ce..** A pointer
10cf0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
10d00 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 of this object i
10d10 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 s the argument t
10d20 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
10d30 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 nfig()] when the
10d40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
10d50 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c ption is.** [SQL
10d60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
10d70 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f C] or [SQLITE_CO
10d80 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e NFIG_GETMALLOC].
10d90 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e .** By creatin
10da0 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 g an instance of
10db0 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 this object.**
10dc0 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 and passing it t
10dd0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
10de0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 g]([SQLITE_CONFI
10df0 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 G_MALLOC]).** du
10e00 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 ring configurati
10e10 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 on, an applicati
10e20 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 on can specify a
10e30 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a n alternative.**
10e40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
10e50 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 on subsystem for
10e60 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 SQLite to use f
10e70 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a or all of its.**
10e80 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 dynamic memory
10e90 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 needs..**.** Not
10ea0 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f e that SQLite co
10eb0 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c mes with several
10ec0 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 [built-in memor
10ed0 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a y allocators].**
10ee0 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 that are perfec
10ef0 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 tly adequate for
10f00 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e the overwhelmin
10f10 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 g majority of ap
10f20 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e plications.** an
10f30 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 d that this obje
10f40 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 ct is only usefu
10f50 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f l to a tiny mino
10f60 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 rity of applicat
10f70 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 ions.** with spe
10f80 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 cialized memory
10f90 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 allocation requi
10fa0 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f rements. This o
10fb0 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f bject is.** also
10fc0 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 used during tes
10fd0 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 ting of SQLite i
10fe0 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 n order to speci
10ff0 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 fy an alternativ
11000 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f e.** memory allo
11010 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c cator that simul
11020 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d ates memory out-
11030 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 of-memory condit
11040 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 ions in.** order
11050 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 to verify that
11060 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 SQLite recovers
11070 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 gracefully from
11080 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f such.** conditio
11090 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d ns..**.** The xM
110a0 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c alloc, xRealloc,
110b0 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f and xFree metho
110c0 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b ds must work lik
110d0 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 e the.** malloc(
110e0 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 ), realloc() and
110f0 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e free() function
11100 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 s from the stand
11110 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a ard C library..*
11120 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e * ^SQLite guaran
11130 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 tees that the se
11140 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
11150 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 .** xRealloc is
11160 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 always a value r
11170 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 eturned by a pri
11180 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e or call to xRoun
11190 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 dup..**.** xSize
111a0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 should return t
111b0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
111c0 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c e of a memory al
111d0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 location.** prev
111e0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 iously obtained
111f0 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 from xMalloc or
11200 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 xRealloc. The a
11210 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a llocated size.**
11220 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 is always at le
11230 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 ast as big as th
11240 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 e requested size
11250 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 but may be larg
11260 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 er..**.** The xR
11270 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 oundup method re
11280 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 turns what would
11290 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 be the allocate
112a0 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d d size of.** a m
112b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
112c0 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 given a particu
112d0 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 lar requested si
112e0 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 ze. Most memory
112f0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 .** allocators r
11300 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 ound up memory a
11310 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 llocations at le
11320 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 ast to the next
11330 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 multiple.** of 8
11340 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f . Some allocato
11350 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 rs round up to a
11360 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 larger multiple
11370 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f or to a power o
11380 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 f 2..** Every me
11390 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
113a0 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 request coming i
113b0 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 n through [sqlit
113c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 e3_malloc()].**
113d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c or [sqlite3_real
113e0 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c loc()] first cal
113f0 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 ls xRoundup. If
11400 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e xRoundup return
11410 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 s 0, .** that ca
11420 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 uses the corresp
11430 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c onding memory al
11440 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c location to fail
11450 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 ..**.** The xIni
11460 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c t method initial
11470 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 izes the memory
11480 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 allocator. For
11490 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d example,.** it m
114a0 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e ight allocate an
114b0 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 y require mutexe
114c0 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 s or initialize
114d0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a internal data.**
114e0 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 structures. Th
114f0 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 e xShutdown meth
11500 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 od is invoked (i
11510 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a ndirectly) by.**
11520 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
11530 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 wn()] and should
11540 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 deallocate any
11550 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 resources acquir
11560 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 ed.** by xInit.
11570 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f The pAppData po
11580 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 inter is used as
11590 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
115a0 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 ter to.** xInit
115b0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a and xShutdown..*
115c0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 *.** SQLite hold
115d0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 s the [SQLITE_MU
115e0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 TEX_STATIC_MASTE
115f0 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 R] mutex when it
11600 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 invokes.** the
11610 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f xInit method, so
11620 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
11630 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 d need not be th
11640 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a readsafe. The.*
11650 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 * xShutdown meth
11660 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 od is only calle
11670 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
11680 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 shutdown()] so i
11690 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 t does.** not ne
116a0 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 ed to be threads
116b0 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 afe either. For
116c0 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f all other metho
116d0 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f ds, SQLite.** ho
116e0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f lds the [SQLITE_
116f0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d MUTEX_STATIC_MEM
11700 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 ] mutex as long
11710 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 as the.** [SQLIT
11720 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
11730 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f US] configuratio
11740 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e n option is turn
11750 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 ed on (which.**
11760 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 it is by default
11770 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 ) and so the met
11780 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 hods are automat
11790 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 ically serialize
117a0 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 d..** However, i
117b0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 f [SQLITE_CONFIG
117c0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 _MEMSTATUS] is d
117d0 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 isabled, then th
117e0 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f e other.** metho
117f0 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 ds must be threa
11800 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 dsafe or else ma
11810 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 ke their own arr
11820 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a angements for.**
11830 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a serialization..
11840 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
11850 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 l never invoke x
11860 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e Init() more than
11870 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e once without an
11880 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 intervening.**
11890 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 call to xShutdow
118a0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 n()..*/.typedef
118b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
118c0 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 em_methods sqlit
118d0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a e3_mem_methods;.
118e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
118f0 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 em_methods {. v
11900 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 oid *(*xMalloc)(
11910 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a int); /*
11920 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
11930 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 on function */.
11940 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 void (*xFree)(v
11950 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
11960 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 /* Free a prior
11970 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
11980 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 void *(*xRealloc
11990 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f )(void*,int); /
119a0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f * Resize an allo
119b0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
119c0 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b (*xSize)(void*);
119d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 /* Re
119e0 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 turn the size of
119f0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
11a00 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 /. int (*xRound
11a10 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 up)(int);
11a20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 /* Round up r
11a30 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 equest size to a
11a40 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a llocation size *
11a50 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 /. int (*xInit)
11a60 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
11a70 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 /* Initialize
11a80 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
11a90 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
11aa0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 (*xShutdown)(voi
11ab0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 d*); /* Dei
11ac0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
11ad0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
11ae0 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
11af0 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 ta;
11b00 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 /* Argument t
11b10 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 o xInit() and xS
11b20 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a hutdown() */.};.
11b30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
11b40 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f Configuration O
11b50 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 ptions.** KEYWOR
11b60 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 DS: {configurati
11b70 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a on option}.**.**
11b80 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
11b90 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 are the availab
11ba0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 le integer confi
11bb0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
11bc0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 that.** can be
11bd0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
11be0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
11bf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
11c00 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
11c10 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 ..**.** New conf
11c20 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
11c30 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
11c40 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
11c50 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
11c60 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 Existing configu
11c70 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
11c80 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 ight be disconti
11c90 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 nued. Applicati
11ca0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 ons.** should ch
11cb0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 eck the return c
11cc0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ode from [sqlite
11cd0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 3_config()] to m
11ce0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a ake sure that.**
11cf0 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 the call worked
11d00 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
11d10 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
11d20 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
11d30 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
11d40 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
11d50 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
11d60 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
11d70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
11d80 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
11d90 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b **.** <dl>.** [[
11da0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
11db0 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 NGLETHREAD]] <dt
11dc0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
11dd0 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e INGLETHREAD</dt>
11de0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
11df0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
11e00 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
11e10 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
11e20 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
11e30 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e ing mode] to Sin
11e40 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 gle-thread. In
11e50 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 other words, it
11e60 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 disables.** all
11e70 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 mutexing and put
11e80 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 s SQLite into a
11e90 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 mode where it ca
11ea0 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a n only be used.*
11eb0 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 * by a single th
11ec0 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 read. ^If SQLi
11ed0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
11ee0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
11ef0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
11f00 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
11f10 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
11f20 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
11f30 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
11f40 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 ble to change th
11f50 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
11f60 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 e] from its defa
11f70 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 ult.** value of
11f80 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e Single-thread an
11f90 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f d so [sqlite3_co
11fa0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 nfig()] will ret
11fb0 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urn .** [SQLITE_
11fc0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 ERROR] if called
11fd0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
11fe0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
11ff0 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 READ.** configur
12000 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 ation option.</d
12010 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
12020 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
12030 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 READ]] <dt>SQLIT
12040 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
12050 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 READ</dt>.** <dd
12060 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
12070 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
12080 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f option. ^This o
12090 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
120a0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 * [threading mod
120b0 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 e] to Multi-thre
120c0 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f ad. In other wo
120d0 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 rds, it disables
120e0 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 .** mutexing on
120f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
12100 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 tion] and [prepa
12110 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
12120 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 bjects..** The a
12130 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 pplication is re
12140 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 sponsible for se
12150 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 rializing access
12160 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 to.** [database
12170 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e connections] an
12180 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
12190 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 ements]. But ot
121a0 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 her mutexes.** a
121b0 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 re enabled so th
121c0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 at SQLite will b
121d0 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e e safe to use in
121e0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 a multi-threade
121f0 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 d.** environment
12200 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 as long as no t
12210 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d wo threads attem
12220 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 pt to use the sa
12230 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 me.** [database
12240 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 connection] at t
12250 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e he same time. ^
12260 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
12270 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
12280 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
12290 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
122a0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
122b0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
122c0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f then.** it is no
122d0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 t possible to se
122e0 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 t the Multi-thre
122f0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ad [threading mo
12300 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 de] and.** [sqli
12310 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
12320 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
12330 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c E_ERROR] if call
12340 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 ed with the.** S
12350 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
12360 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 TITHREAD configu
12370 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
12380 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
12390 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
123a0 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 IZED]] <dt>SQLIT
123b0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
123c0 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ZED</dt>.** <dd>
123d0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
123e0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
123f0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 ption. ^This op
12400 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
12410 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
12420 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e ] to Serialized.
12430 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
12440 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 this option ena
12450 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 bles.** all mute
12460 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 xes including th
12470 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d e recursive.** m
12480 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 utexes on [datab
12490 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
124a0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
124b0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
124c0 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 ..** In this mod
124d0 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 e (which is the
124e0 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c default when SQL
124f0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
12500 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f with.** [SQLITE_
12510 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 THREADSAFE=1]) t
12520 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
12530 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 y will itself se
12540 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a rialize access.*
12550 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 * to [database c
12560 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 onnections] and
12570 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
12580 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 ents] so that th
12590 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e e.** application
125a0 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 is free to use
125b0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 the same [databa
125c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
125d0 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 r the.** same [p
125e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
125f0 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 t] in different
12600 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 threads at the s
12610 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 ame time..** ^If
12620 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
12630 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
12640 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
12650 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
12660 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
12670 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
12680 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
12690 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 possible to set
126a0 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b the Serialized [
126b0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
126c0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
126d0 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 config()] will r
126e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 eturn [SQLITE_ER
126f0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 ROR] if called w
12700 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 ith the.** SQLIT
12710 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
12720 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ZED configuratio
12730 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a n option.</dd>.*
12740 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
12750 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 NFIG_MALLOC]] <d
12760 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
12770 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
12780 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 dd> ^(The SQLITE
12790 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f _CONFIG_MALLOC o
127a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
127b0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
127c0 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 ich is .** a poi
127d0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
127e0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
127f0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
12800 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 structure..** T
12810 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 he argument spec
12820 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 ifies.** alterna
12830 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d tive low-level m
12840 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
12850 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
12860 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 used in place of
12870 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 .** the memory a
12880 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
12890 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 es built into SQ
128a0 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 Lite.)^ ^SQLite
128b0 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e makes.** its own
128c0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
128d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
128e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
128f0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
12900 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 ure.** before th
12910 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e [sqlite3_confi
12920 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e g()] call return
12930 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b s.</dd>.**.** [[
12940 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
12950 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 TMALLOC]] <dt>SQ
12960 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
12970 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ALLOC</dt>.** <d
12980 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f d> ^(The SQLITE_
12990 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
129a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
129b0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
129c0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f which.** is a po
129d0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
129e0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
129f0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
12a00 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 ] structure..**
12a10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
12a20 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
12a30 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
12a40 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
12a50 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f tly defined memo
12a60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
12a70 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 utines.)^.** Thi
12a80 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 s option can be
12a90 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 used to overload
12aa0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d the default mem
12ab0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
12ac0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 * routines with
12ad0 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 a wrapper that s
12ae0 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 imulations memor
12af0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
12b00 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b lure or.** track
12b10 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 s memory usage,
12b20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 for example. </d
12b30 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
12b40 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
12b50 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f US]] <dt>SQLITE_
12b60 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
12b70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
12b80 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
12b90 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f _MEMSTATUS optio
12ba0 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 n takes single a
12bb0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 rgument of type
12bc0 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 int,.** interpre
12bd0 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e ted as a boolean
12be0 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 , which enables
12bf0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 or disables the
12c00 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a collection of.**
12c10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
12c20 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e on statistics. ^
12c30 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c (When memory all
12c40 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
12c50 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c cs are.** disabl
12c60 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e ed, the followin
12c70 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 g SQLite interfa
12c80 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f ces become non-o
12c90 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 perational:.**
12ca0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 <ul>.** <li>
12cb0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
12cc0 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 used()].** <li
12cd0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 > [sqlite3_memor
12ce0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a y_highwater()].*
12cf0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
12d00 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
12d10 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e t64()].** <li>
12d20 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 [sqlite3_status
12d30 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 64()].** </ul>
12d40 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c )^.** ^Memory al
12d50 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 location statist
12d60 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 ics are enabled
12d70 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 by default unles
12d80 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 s SQLite is.** c
12d90 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 ompiled with [SQ
12da0 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d LITE_DEFAULT_MEM
12db0 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 STATUS]=0 in whi
12dc0 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a ch case memory.*
12dd0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 * allocation sta
12de0 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 tistics are disa
12df0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e bled by default.
12e00 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
12e10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
12e20 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 SCRATCH]] <dt>SQ
12e30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
12e40 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TCH</dt>.** <dd>
12e50 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^The SQLITE_CON
12e60 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 FIG_SCRATCH opti
12e70 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 on specifies a s
12e80 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 tatic memory buf
12e90 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 fer.** that SQLi
12ea0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 te can use for s
12eb0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 cratch memory.
12ec0 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65 ^(There are thre
12ed0 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 e arguments.** t
12ee0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f o SQLITE_CONFIG_
12ef0 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e SCRATCH: A poin
12f00 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a ter an 8-byte.**
12f10 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 aligned memory
12f20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 buffer from whic
12f30 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c h the scratch al
12f40 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 locations will b
12f50 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 e.** drawn, the
12f60 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 size of each scr
12f70 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 atch allocation
12f80 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 (sz),.** and the
12f90 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
12fa0 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 of scratch alloc
12fb0 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a ations (N).)^.**
12fc0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
12fd0 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f ent must be a po
12fe0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 inter to an 8-by
12ff0 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 te aligned buffe
13000 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 r.** of at least
13010 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d sz*N bytes of m
13020 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 emory..** ^SQLit
13030 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d e will not use m
13040 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 ore than one scr
13050 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 atch buffers per
13060 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c thread..** ^SQL
13070 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 ite will never r
13080 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68 equest a scratch
13090 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 buffer that is
130a0 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 more than 6.** t
130b0 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 imes the databas
130c0 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 e page size..**
130d0 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 ^If SQLite needs
130e0 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 needs additiona
130f0 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d l.** scratch mem
13100 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 ory beyond what
13110 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 is provided by t
13120 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f his configuratio
13130 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a n option, then .
13140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
13150 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 oc()] will be us
13160 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 ed to obtain the
13170 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c memory needed.<
13180 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 p>.** ^When the
13190 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 application prov
131a0 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 ides any amount
131b0 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 of scratch memor
131c0 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 y using.** SQLIT
131d0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
131e0 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 , SQLite avoids
131f0 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 unnecessary larg
13200 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 e.** [sqlite3_ma
13210 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 lloc|heap alloca
13220 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 tions]..** This
13230 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e can help [Robson
13240 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d proof|prevent m
13250 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
13260 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 failures] due t
13270 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 o heap.** fragme
13280 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d ntation in low-m
13290 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 emory embedded s
132a0 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e ystems..** </dd>
132b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
132c0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
132d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
132e0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f NFIG_PAGECACHE</
132f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 dt>.** <dd> ^The
13300 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
13310 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 AGECACHE option
13320 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 specifies a stat
13330 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ic memory buffer
13340 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 .** that SQLite
13350 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 can use for the
13360 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 database page ca
13370 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 che with the def
13380 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 ault page.** cac
13390 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
133a0 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e n. .** This con
133b0 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c figuration shoul
133c0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 d not be used if
133d0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
133e0 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 define page.** c
133f0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
13400 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 ion is loaded us
13410 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
13420 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a CONFIG_PCACHE2].
13430 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
13440 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 option..** ^The
13450 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
13460 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 uments to SQLITE
13470 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
13480 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a E: A pointer to.
13490 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 ** 8-byte aligne
134a0 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 d.** memory, the
134b0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 size of each pa
134c0 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 ge buffer (sz),
134d0 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f and the number o
134e0 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 f pages (N)..**
134f0 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 The sz argument
13500 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 should be the si
13510 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 ze of the larges
13520 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a t database page.
13530 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 ** (a power of t
13540 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 wo between 512 a
13550 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 nd 65536) plus s
13560 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20 ome extra bytes
13570 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 for each.** page
13580 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e header. ^The n
13590 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 umber of extra b
135a0 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 ytes needed by t
135b0 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a he page header.*
135c0 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 * can be determi
135d0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 ned using the [S
135e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
135f0 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f CHE_HDRSZ] optio
13600 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 n .** to [sqlite
13610 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 3_config()]..**
13620 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c ^It is harmless,
13630 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 apart from the
13640 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a wasted memory,.*
13650 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 * for the sz par
13660 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 ameter to be lar
13670 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 ger than necessa
13680 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a ry. The first.*
13690 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c * argument shoul
136a0 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 d pointer to an
136b0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 8-byte aligned b
136c0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74 lock of memory t
136d0 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61 hat.** is at lea
136e0 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 st sz*N bytes of
136f0 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69 memory, otherwi
13700 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 se subsequent be
13710 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 havior is.** und
13720 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 efined..** ^SQLi
13730 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 te will use the
13740 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 memory provided
13750 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 by the first arg
13760 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 ument to satisfy
13770 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e its.** memory n
13780 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 eeds for the fir
13790 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 st N pages that
137a0 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 it adds to cache
137b0 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 . ^If additiona
137c0 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 l.** page cache
137d0 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 memory is needed
137e0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 beyond what is
137f0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 provided by this
13800 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a option, then.**
13810 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 SQLite goes to
13820 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
13830 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 )] for the addit
13840 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 ional storage sp
13850 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ace.</dd>.**.**
13860 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
13870 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 HEAP]] <dt>SQLIT
13880 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 E_CONFIG_HEAP</d
13890 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 t>.** <dd> ^The
138a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
138b0 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 AP option specif
138c0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d ies a static mem
138d0 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 ory buffer .** t
138e0 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
138f0 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 use for all of i
13900 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 ts dynamic memor
13910 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
13920 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f ds.** beyond tho
13930 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 se provided for
13940 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 by [SQLITE_CONFI
13950 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a G_SCRATCH] and.*
13960 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
13970 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 _PAGECACHE]..**
13980 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
13990 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 IG_HEAP option i
139a0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 s only available
139b0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
139c0 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 mpiled.** with e
139d0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e ither [SQLITE_EN
139e0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 ABLE_MEMSYS3] or
139f0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
13a00 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 MEMSYS5] and ret
13a10 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urns.** [SQLITE_
13a20 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 ERROR] if invoke
13a30 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 d otherwise..**
13a40 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 ^There are three
13a50 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 arguments to SQ
13a60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
13a70 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 :.** An 8-byte a
13a80 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 ligned pointer t
13a90 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a o the memory,.**
13aa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
13ab0 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f ytes in the memo
13ac0 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 ry buffer, and t
13ad0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 he minimum alloc
13ae0 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e ation size..** ^
13af0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 If the first poi
13b00 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 nter (the memory
13b10 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c pointer) is NUL
13b20 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 L, then SQLite r
13b30 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 everts.** to usi
13b40 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d ng its default m
13b50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
13b60 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c (the system mall
13b70 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 oc() implementat
13b80 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 ion),.** undoing
13b90 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 any prior invoc
13ba0 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 ation of [SQLITE
13bb0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e _CONFIG_MALLOC].
13bc0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d ^If the.** mem
13bd0 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e ory pointer is n
13be0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 ot NULL then the
13bf0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d alternative mem
13c00 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 ory.** allocator
13c10 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 is engaged to h
13c20 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c andle all of SQL
13c30 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ites memory allo
13c40 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a cation needs..**
13c50 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 The first point
13c60 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 er (the memory p
13c70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 ointer) must be
13c80 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d aligned to an 8-
13c90 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 byte.** boundary
13ca0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 or subsequent b
13cb0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 ehavior of SQLit
13cc0 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 e will be undefi
13cd0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 ned..** The mini
13ce0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 mum allocation s
13cf0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 ize is capped at
13d00 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 2**12. Reasonab
13d10 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 le values.** for
13d20 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
13d30 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 ocation size are
13d40 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2**5 through 2*
13d50 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b *8.</dd>.**.** [
13d60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
13d70 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 UTEX]] <dt>SQLIT
13d80 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f E_CONFIG_MUTEX</
13d90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
13da0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
13db0 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b MUTEX option tak
13dc0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
13dd0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a ment which is a.
13de0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e ** pointer to an
13df0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
13e00 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
13e10 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
13e20 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d re..** The argum
13e30 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c ent specifies al
13e40 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 ternative low-le
13e50 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e vel mutex routin
13e60 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a es to be used.**
13e70 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 in place the mu
13e80 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 tex routines bui
13e90 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 lt into SQLite.)
13ea0 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 ^ ^SQLite makes
13eb0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 a copy of.** th
13ec0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
13ed0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
13ee0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
13ef0 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 re before the ca
13f00 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
13f10 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 3_config()] retu
13f20 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 rns. ^If SQLite
13f30 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
13f40 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
13f50 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
13f60 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
13f70 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
13f80 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 ption then.** th
13f90 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e e entire mutexin
13fa0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f g subsystem is o
13fb0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 mitted from the
13fc0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 build and hence
13fd0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c calls to.** [sql
13fe0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
13ff0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 ith the SQLITE_C
14000 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 ONFIG_MUTEX conf
14010 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
14020 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 will.** return
14030 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c [SQLITE_ERROR].<
14040 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
14050 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
14060 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 TEX]] <dt>SQLITE
14070 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
14080 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
14090 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
140a0 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f G_GETMUTEX optio
140b0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
140c0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a argument which.
140d0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ** is a pointer
140e0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
140f0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
14100 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 utex_methods] st
14110 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a ructure. The.**
14120 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
14130 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 methods].** stru
14140 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 cture is filled
14150 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 with the current
14160 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 ly defined mutex
14170 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 routines.)^.**
14180 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 This option can
14190 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c be used to overl
141a0 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 oad the default
141b0 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e mutex allocation
141c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 .** routines wit
141d0 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 h a wrapper used
141e0 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 to track mutex
141f0 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 usage for perfor
14200 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 mance.** profili
14210 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 ng or testing, f
14220 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 or example. ^I
14230 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
14240 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
14250 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
14260 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
14270 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
14280 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
14290 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 hen.** the entir
142a0 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 e mutexing subsy
142b0 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 stem is omitted
142c0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 from the build a
142d0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 nd hence calls t
142e0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
142f0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 nfig()] with the
14300 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
14310 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 ETMUTEX configur
14320 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c ation option wil
14330 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c l.** return [SQL
14340 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e ITE_ERROR].</dd>
14350 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
14360 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
14370 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
14380 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
14390 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
143a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
143b0 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e LOOKASIDE option
143c0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d takes two argum
143d0 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d ents that determ
143e0 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 ine.** the defau
143f0 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 lt size of looka
14400 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 side memory on e
14410 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f ach [database co
14420 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 nnection]..** Th
14430 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
14440 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 is the.** size
14450 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 of each lookasid
14460 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e e buffer slot an
14470 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 d the second is
14480 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
14490 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 slots allocated
144a0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 to each databas
144b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 e connection.)^
144c0 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ^(SQLITE_CONFIG
144d0 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 _LOOKASIDE.** se
144e0 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c ts the <i>defaul
144f0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 t</i> lookaside
14500 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 size. The [SQLIT
14510 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
14520 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 SIDE].** option
14530 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 to [sqlite3_db_c
14540 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 onfig()] can be
14550 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 used to change t
14560 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 he lookaside.**
14570 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e configuration on
14580 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e individual conn
14590 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e ections.)^ </dd>
145a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
145b0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d CONFIG_PCACHE2]]
145c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
145d0 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a IG_PCACHE2</dt>.
145e0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
145f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
14600 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 HE2 option takes
14610 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
14620 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 nt which is .**
14630 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
14640 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
14650 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 methods2] object
14660 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 . This object s
14670 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 pecifies.** the
14680 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 interface to a c
14690 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 ustom page cache
146a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
146b0 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 )^.** ^SQLite ma
146c0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
146d0 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 e [sqlite3_pcach
146e0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 e_methods2] obje
146f0 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ct.</dd>.**.** [
14700 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
14710 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e ETPCACHE2]] <dt>
14720 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
14730 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a TPCACHE2</dt>.**
14740 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 <dd> ^(The SQLI
14750 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
14760 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 CHE2 option take
14770 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
14780 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ent which.** is
14790 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
147a0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
147b0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 methods2] object
147c0 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 . SQLite copies
147d0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 of.** the curre
147e0 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d nt page cache im
147f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 plementation int
14800 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e o that object.)^
14810 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
14820 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
14830 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
14840 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a NFIG_LOG</dt>.**
14850 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 <dd> The SQLITE
14860 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 _CONFIG_LOG opti
14870 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f on is used to co
14880 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 nfigure the SQLi
14890 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 te.** global [er
148a0 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 ror log]..** (^T
148b0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
148c0 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 _LOG option take
148d0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a s two arguments:
148e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a a pointer to a.
148f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 ** function with
14900 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 a call signatur
14910 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 e of void(*)(voi
14920 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
14930 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 r*), .** and a p
14940 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 ointer to void.
14950 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e ^If the function
14960 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
14970 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 NULL, it is.** i
14980 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 nvoked by [sqlit
14990 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f e3_log()] to pro
149a0 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e cess each loggin
149b0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 g event. ^If th
149c0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f e.** function po
149d0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 inter is NULL, t
149e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 he [sqlite3_log(
149f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 )] interface bec
14a00 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a omes a no-op..**
14a10 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 ^The void point
14a20 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 er that is the s
14a30 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
14a40 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f o SQLITE_CONFIG_
14a50 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 LOG is.** passed
14a60 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 through as the
14a70 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
14a80 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 to the applicati
14a90 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 on-defined logge
14aa0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 r.** function wh
14ab0 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 enever that func
14ac0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e tion is invoked.
14ad0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 ^The second pa
14ae0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 rameter to.** th
14af0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f e logger functio
14b00 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 n is a copy of t
14b10 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
14b20 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 er to the corres
14b30 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 ponding.** [sqli
14b40 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 te3_log()] call
14b50 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 and is intended
14b60 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 to be a [result
14b70 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b code] or an.** [
14b80 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
14b90 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 code]. ^The thi
14ba0 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 rd parameter pas
14bb0 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 sed to the logge
14bc0 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 r is.** log mess
14bd0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 age after format
14be0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 ting via [sqlite
14bf0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 3_snprintf()]..*
14c00 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 * The SQLite log
14c10 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 ging interface i
14c20 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b s not reentrant;
14c30 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 the logger func
14c40 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 tion.** supplied
14c50 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
14c60 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 ion must not inv
14c70 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 oke any SQLite i
14c80 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 nterface..** In
14c90 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 a multi-threaded
14ca0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 application, th
14cb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
14cc0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 fined logger.**
14cd0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 function must be
14ce0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 threadsafe. </d
14cf0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
14d00 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c E_CONFIG_URI]] <
14d10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
14d20 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 _URI.** <dd>^(Th
14d30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
14d40 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 URI option takes
14d50 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
14d60 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a nt of type int..
14d70 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 ** If non-zero,
14d80 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e then URI handlin
14d90 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e g is globally en
14da0 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 abled. If the pa
14db0 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c rameter is zero,
14dc0 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e .** then URI han
14dd0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c dling is globall
14de0 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 y disabled.)^ ^I
14df0 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 f URI handling i
14e00 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e s globally.** en
14e10 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e abled, all filen
14e20 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b ames passed to [
14e30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
14e40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
14e50 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 2()],.** [sqlite
14e60 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 3_open16()] or.*
14e70 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 * specified as p
14e80 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 art of [ATTACH]
14e90 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 commands are int
14ea0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 erpreted as URIs
14eb0 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 , regardless.**
14ec0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
14ed0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 t the [SQLITE_OP
14ee0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 EN_URI] flag is
14ef0 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 set when the dat
14f00 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
14f10 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e ion is opened. ^
14f20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c If it is globall
14f30 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 y disabled, file
14f40 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c names are.** onl
14f50 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 y interpreted as
14f60 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c URIs if the SQL
14f70 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 ITE_OPEN_URI fla
14f80 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 g is set when th
14f90 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
14fa0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e nnection is open
14fb0 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 ed. ^(By default
14fc0 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 , URI handling i
14fd0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 s globally.** di
14fe0 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 sabled. The defa
14ff0 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 ult value may be
15000 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 changed by comp
15010 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a iling with the.*
15020 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 * [SQLITE_USE_UR
15030 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 I] symbol define
15040 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d.)^.**.** [[SQL
15050 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
15060 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d ING_INDEX_SCAN]]
15070 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
15080 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 IG_COVERING_INDE
15090 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 X_SCAN.** <dd>^T
150a0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
150b0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f _COVERING_INDEX_
150c0 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 SCAN option take
150d0 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 s a single integ
150e0 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 er.** argument w
150f0 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 hich is interpre
15100 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e ted as a boolean
15110 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 in order to ena
15120 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a ble or disable.*
15130 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 * the use of cov
15140 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f ering indices fo
15150 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 r full table sca
15160 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 ns in the query
15170 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 optimizer..** ^T
15180 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 he default setti
15190 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 ng is determined
151a0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 .** by the [SQLI
151b0 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e TE_ALLOW_COVERIN
151c0 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f G_INDEX_SCAN] co
151d0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
151e0 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a n, or is "on".**
151f0 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 if that compile
15200 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 -time option is
15210 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 omitted..** The
15220 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 ability to disab
15230 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f le the use of co
15240 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 vering indices f
15250 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 or full table sc
15260 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 ans.** is becaus
15270 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 e some incorrect
15280 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 ly coded legacy
15290 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 applications mig
152a0 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a ht malfunction.*
152b0 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d * when the optim
152c0 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c ization is enabl
152d0 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 ed. Providing t
152e0 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a he ability to.**
152f0 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 disable the opt
15300 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 imization allows
15310 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 the older, bugg
15320 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f y application co
15330 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 de to work.** wi
15340 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 thout change eve
15350 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 n with newer ver
15360 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e sions of SQLite.
15370 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
15380 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 CONFIG_PCACHE]]
15390 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
153a0 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c GETPCACHE]].** <
153b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
153c0 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 _PCACHE and SQLI
153d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
153e0 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 CHE.** <dd> Thes
153f0 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 e options are ob
15400 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c solete and shoul
15410 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 d not be used by
15420 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 new code..** Th
15430 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 ey are retained
15440 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f for backwards co
15450 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 mpatibility but
15460 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a are now no-ops..
15470 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ** </dd>.**.** [
15480 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
15490 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 QLLOG]].** <dt>S
154a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c QLITE_CONFIG_SQL
154b0 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 LOG.** <dd>This
154c0 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 option is only a
154d0 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 vailable if sqli
154e0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
154f0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
15500 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 TE_ENABLE_SQLLOG
15510 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 ] pre-processor
15520 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 macro defined. T
15530 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
15540 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 t should.** be a
15550 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 pointer to a fu
15560 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 nction of type v
15570 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
15580 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 ite3*,const char
15590 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 *, int)..** The
155a0 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 second should be
155b0 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 of type (void*)
155c0 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 . The callback i
155d0 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 s invoked by the
155e0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 library.** in t
155f0 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 hree separate ci
15600 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 rcumstances, ide
15610 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 ntified by the v
15620 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 alue passed as t
15630 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 he.** fourth par
15640 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 ameter. If the f
15650 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
15660 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 is 0, then the d
15670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
15680 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 on.** passed as
15690 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
156a0 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 ent has just bee
156b0 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 n opened. The th
156c0 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ird argument.**
156d0 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 points to a buff
156e0 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 er containing th
156f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 e name of the ma
15700 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 in database file
15710 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 . If the.** four
15720 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
15730 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 1, then the SQL
15740 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 statement that t
15750 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
15760 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 er.** points to
15770 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 has just been ex
15780 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 ecuted. Or, if t
15790 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
157a0 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a ter is 2, then.*
157b0 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e * the connection
157c0 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 being passed as
157d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
157e0 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 meter is being c
157f0 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 losed. The.** th
15800 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
15810 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 passed NULL In
15820 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 this case. An e
15830 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 xample of using
15840 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 this.** configur
15850 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e ation option can
15860 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 be seen in the
15870 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 "test_sqllog.c"
15880 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a source file in.*
15890 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 * the canonical
158a0 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 SQLite source tr
158b0 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ee.</dd>.**.** [
158c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
158d0 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 MAP_SIZE]].** <d
158e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
158f0 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 MMAP_SIZE.** <dd
15900 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f >^SQLITE_CONFIG_
15910 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 MMAP_SIZE takes
15920 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 two 64-bit integ
15930 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 er (sqlite3_int6
15940 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 4) values.** tha
15950 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c t are the defaul
15960 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 t mmap size limi
15970 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 t (the default s
15980 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 etting for.** [P
15990 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d RAGMA mmap_size]
159a0 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 ) and the maximu
159b0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 m allowed mmap s
159c0 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 ize limit..** ^T
159d0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 he default setti
159e0 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 ng can be overri
159f0 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 dden by each dat
15a00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
15a10 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 using.** either
15a20 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 the [PRAGMA mma
15a30 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c p_size] command,
15a40 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 or by using the
15a50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 .** [SQLITE_FCNT
15a60 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c L_MMAP_SIZE] fil
15a70 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 e control. ^(Th
15a80 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 e maximum allowe
15a90 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 d mmap size.** w
15aa0 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 ill be silently
15ab0 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 truncated if nec
15ac0 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 essary so that i
15ad0 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 t does not excee
15ae0 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 d the.** compile
15af0 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d -time maximum mm
15b00 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 ap size set by t
15b10 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 he.** [SQLITE_MA
15b20 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d X_MMAP_SIZE] com
15b30 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
15b40 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 .)^.** ^If eithe
15b50 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 r argument to th
15b60 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 is option is neg
15b70 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 ative, then that
15b80 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 argument is.**
15b90 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 changed to its c
15ba0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 ompile-time defa
15bb0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c ult..**.** [[SQL
15bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 ITE_CONFIG_WIN32
15bd0 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c _HEAPSIZE]].** <
15be0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
15bf0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a _WIN32_HEAPSIZE.
15c00 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 ** <dd>^The SQLI
15c10 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f TE_CONFIG_WIN32_
15c20 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 HEAPSIZE option
15c30 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c is only availabl
15c40 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a e if SQLite is.*
15c50 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 * compiled for W
15c60 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 indows with the
15c70 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 [SQLITE_WIN32_MA
15c80 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 LLOC] pre-proces
15c90 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 sor macro.** def
15ca0 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f ined. ^SQLITE_CO
15cb0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 NFIG_WIN32_HEAPS
15cc0 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 IZE takes a 32-b
15cd0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 it unsigned inte
15ce0 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 ger value.** tha
15cf0 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 t specifies the
15d00 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 maximum size of
15d10 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70 the created heap
15d20 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ..**.** [[SQLITE
15d30 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 _CONFIG_PCACHE_H
15d40 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 DRSZ]].** <dt>SQ
15d50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
15d60 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e HE_HDRSZ.** <dd>
15d70 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
15d80 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 IG_PCACHE_HDRSZ
15d90 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
15da0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 ingle parameter
15db0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f which.** is a po
15dc0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
15dd0 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 ger and writes i
15de0 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 nto that integer
15df0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
15e00 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 xtra.** bytes pe
15e10 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20 r page required
15e20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e for each page in
15e30 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
15e40 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 PAGECACHE]..** T
15e50 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 he amount of ext
15e60 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65 ra space require
15e70 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 d can change dep
15e80 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f ending on the co
15e90 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 mpiler,.** targe
15ea0 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 t platform, and
15eb0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a SQLite version..
15ec0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
15ed0 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a ONFIG_PMASZ]].**
15ee0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
15ef0 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e IG_PMASZ.** <dd>
15f00 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
15f10 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 IG_PMASZ option
15f20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 takes a single p
15f30 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a arameter which.*
15f40 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 * is an unsigned
15f50 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 integer and set
15f60 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 s the "Minimum P
15f70 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 MA Size" for the
15f80 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a multithreaded.*
15f90 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 * sorter to that
15fa0 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 integer. The d
15fb0 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 efault minimum P
15fc0 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 MA Size is set b
15fd0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 y the.** [SQLITE
15fe0 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 _SORTER_PMASZ] c
15ff0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
16000 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 on. New threads
16010 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a are launched.**
16020 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f to help with so
16030 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 rt operations wh
16040 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 en multithreaded
16050 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 sorting.** is e
16060 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 nabled (using th
16070 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 e [PRAGMA thread
16080 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 s] command) and
16090 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f the amount of co
160a0 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 ntent.** to be s
160b0 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68 orted exceeds th
160c0 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 e page size time
160d0 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 s the minimum of
160e0 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 the.** [PRAGMA
160f0 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 cache_size] sett
16100 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c ing and this val
16110 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a ue..** </dl>.*/.
16120 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16130 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
16140 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f AD 1 /* nil */
16150 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16160 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
16170 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a AD 2 /* nil *
16180 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16190 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a _CONFIG_SERIALIZ
161a0 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 ED 3 /* nil
161b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
161c0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 E_CONFIG_MALLOC
161d0 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 4 /* sql
161e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
161f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
16200 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
16210 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 LLOC 5 /* s
16220 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
16230 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
16240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
16250 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a ATCH 6 /*
16260 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 void*, int sz,
16270 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 int N */.#define
16280 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
16290 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 AGECACHE 7
162a0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a /* void*, int sz
162b0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 , int N */.#defi
162c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
162d0 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 _HEAP 8
162e0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
162f0 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a nByte, int min *
16300 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16310 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
16320 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c S 9 /* bool
16330 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ean */.#define S
16340 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
16350 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a EX 10 /*
16360 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
16370 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
16380 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16390 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 _GETMUTEX 11
163a0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 /* sqlite3_mut
163b0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f ex_methods* */./
163c0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c * previously SQL
163d0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b ITE_CONFIG_CHUNK
163e0 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 ALLOC 12 which i
163f0 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f s now unused. */
16400 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .#define SQLITE
16410 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
16420 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 E 13 /* int
16430 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
16440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
16450 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a CHE 14 /*
16460 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e no-op */.#defin
16470 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16480 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 GETPCACHE 15
16490 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 /* no-op */.#de
164a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
164b0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 IG_LOG
164c0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 16 /* xFunc, vo
164d0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 id* */.#define S
164e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
164f0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 17 /*
16500 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
16510 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
16520 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f ACHE2 18 /
16530 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 * sqlite3_pcache
16540 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 _methods2* */.#d
16550 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
16560 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 FIG_GETPCACHE2
16570 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 19 /* sqlite3_
16580 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a pcache_methods2*
16590 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
165a0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 TE_CONFIG_COVERI
165b0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 NG_INDEX_SCAN 20
165c0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 /* int */.#def
165d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
165e0 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 G_SQLLOG 2
165f0 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 1 /* xSqllog, v
16600 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 oid* */.#define
16610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d SQLITE_CONFIG_MM
16620 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f AP_SIZE 22 /
16630 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c * sqlite3_int64,
16640 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
16650 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16660 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 _CONFIG_WIN32_HE
16670 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 APSIZE 23
16680 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a /* int nByte */.
16690 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
166a0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 ONFIG_PCACHE_HDR
166b0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a SZ 24 /*
166c0 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 int *psz */.#de
166d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
166e0 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 IG_PMASZ
166f0 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 25 /* un
16700 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 signed int szPma
16710 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
16720 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f REF: Database Co
16730 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 nnection Configu
16740 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a ration Options.*
16750 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
16760 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 ants are the ava
16770 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 ilable integer c
16780 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
16790 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e ions that.** can
167a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
167b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
167c0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 t to the [sqlite
167d0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 3_db_config()] i
167e0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
167f0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f New configuratio
16800 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 n options may be
16810 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
16820 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
16830 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 ite..** Existing
16840 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
16850 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 ptions might be
16860 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 discontinued. A
16870 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
16880 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 hould check the
16890 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d return code from
168a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
168b0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 fig()] to make s
168c0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ure that.** the
168d0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 call worked. ^T
168e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 he [sqlite3_db_c
168f0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 onfig()] interfa
16900 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 ce will return a
16910 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 .** non-zero [er
16920 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 ror code] if a d
16930 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 iscontinued or u
16940 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 nsupported confi
16950 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a guration option.
16960 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a ** is invoked..*
16970 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
16980 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
16990 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a _LOOKASIDE</dt>.
169a0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
169b0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 tion takes three
169c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
169d0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 ments that deter
169e0 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f mine the .** [lo
169f0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
16a00 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 llocator] config
16a10 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 uration for the
16a20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
16a30 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 tion]..** ^The f
16a40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 irst argument (t
16a50 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
16a60 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 er to [sqlite3_d
16a70 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 b_config()] is a
16a80 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 .** pointer to a
16a90 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
16aa0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 o use for lookas
16ab0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e ide memory..** ^
16ac0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
16ad0 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c nt after the SQL
16ae0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
16af0 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d KASIDE verb.** m
16b00 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 ay be NULL in wh
16b10 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 ich case SQLite
16b20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 will allocate th
16b30 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 e.** lookaside b
16b40 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 uffer itself usi
16b50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ng [sqlite3_mall
16b60 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f oc()]. ^The seco
16b70 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
16b80 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 he.** size of ea
16b90 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 ch lookaside buf
16ba0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 fer slot. ^The
16bb0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
16bc0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
16bd0 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 ** slots. The s
16be0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 ize of the buffe
16bf0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 r in the first a
16c00 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
16c10 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 greater than.**
16c20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 or equal to the
16c30 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 product of the s
16c40 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 econd and third
16c50 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 arguments. The
16c60 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 buffer.** must b
16c70 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
16c80 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 8-byte boundary.
16c90 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 ^If the second
16ca0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
16cb0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
16cc0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 LOOKASIDE is not
16cd0 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 a multiple of 8
16ce0 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c , it is internal
16cf0 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f ly.** rounded do
16d00 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 wn to the next s
16d10 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 maller multiple
16d20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f of 8. ^(The loo
16d30 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a kaside memory.**
16d40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 configuration f
16d50 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f or a database co
16d60 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c nnection can onl
16d70 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 y be changed whe
16d80 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 n that.** connec
16d90 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 tion is not curr
16da0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b ently using look
16db0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 aside memory, or
16dc0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a in other words.
16dd0 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 ** when the "cur
16de0 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 rent value" retu
16df0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
16e00 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 te3_db_status](D
16e10 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ,[SQLITE_CONFIG_
16e20 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 LOOKASIDE],...)
16e30 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 is zero..** Any
16e40 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 attempt to chang
16e50 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 e the lookaside
16e60 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 memory configura
16e70 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 tion when lookas
16e80 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 ide.** memory is
16e90 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 in use leaves t
16ea0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e he configuration
16eb0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 unchanged and r
16ec0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 eturns .** [SQLI
16ed0 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e TE_BUSY].)^</dd>
16ee0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
16ef0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
16f00 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c E_FKEY</dt>.** <
16f10 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
16f20 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 is used to enab
16f30 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 le or disable th
16f40 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 e enforcement of
16f50 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 .** [foreign key
16f60 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 constraints].
16f70 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 There should be
16f80 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 two additional a
16f90 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 rguments..** The
16fa0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
16fb0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 is an integer wh
16fc0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 ich is 0 to disa
16fd0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 ble FK enforceme
16fe0 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 nt,.** positive
16ff0 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 to enable FK enf
17000 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 orcement or nega
17010 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b tive to leave FK
17020 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 enforcement.**
17030 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 unchanged. The
17040 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
17050 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
17060 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f an integer into
17070 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 which.** is wri
17080 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 tten 0 or 1 to i
17090 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 ndicate whether
170a0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 FK enforcement i
170b0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 s off or on.** f
170c0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 ollowing this ca
170d0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ll. The second
170e0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
170f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
17100 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 in.** which cas
17110 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 e the FK enforce
17120 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 ment setting is
17130 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 not reported bac
17140 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c k. </dd>.**.** <
17150 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
17160 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 IG_ENABLE_TRIGGE
17170 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e R</dt>.** <dd> ^
17180 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 This option is u
17190 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 sed to enable or
171a0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 disable [CREATE
171b0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 TRIGGER | trigg
171c0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 ers]..** There s
171d0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 hould be two add
171e0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
171f0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 s..** The first
17200 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 argument is an i
17210 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
17220 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 0 to disable tri
17230 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 ggers,.** positi
17240 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 ve to enable tri
17250 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 ggers or negativ
17260 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 e to leave the s
17270 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 etting unchanged
17280 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
17290 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
172a0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
172b0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a eger into which.
172c0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ** is written 0
172d0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
172e0 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 whether trigger
172f0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f s are disabled o
17300 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c r enabled.** fol
17310 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c lowing this call
17320 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
17330 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 rameter may be a
17340 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 NULL pointer, i
17350 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 n.** which case
17360 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 the trigger sett
17370 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 ing is not repor
17380 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a ted back. </dd>.
17390 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 **.** </dl>.*/.#
173a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
173b0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
173c0 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 1001 /*
173d0 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f void* int int */
173e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
173f0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
17400 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f FKEY 1002 /
17410 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 * int int* */.#d
17420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
17430 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 ONFIG_ENABLE_TRI
17440 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 GGER 1003 /* i
17450 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a nt int* */.../*.
17460 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 ** CAPI3REF: Ena
17470 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 ble Or Disable E
17480 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 xtended Result C
17490 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 odes.** METHOD:
174a0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
174b0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e he sqlite3_exten
174c0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
174d0 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c () routine enabl
174e0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
174f0 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 he.** [extended
17500 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 result codes] fe
17510 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e ature of SQLite.
17520 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 ^The extended r
17530 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 esult.** codes a
17540 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 re disabled by d
17550 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f efault for histo
17560 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c rical compatibil
17570 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ity..*/.SQLITE_A
17580 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
17590 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 DCALL sqlite3_ex
175a0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
175b0 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e des(sqlite3*, in
175c0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a t onoff);../*.**
175d0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 CAPI3REF: Last
175e0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 Insert Rowid.**
175f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
17600 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 **.** ^Each entr
17610 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 y in most SQLite
17620 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 tables (except
17630 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 for [WITHOUT ROW
17640 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 ID] tables).** h
17650 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 as a unique 64-b
17660 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 it signed.** int
17670 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 eger key called
17680 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f the [ROWID | "ro
17690 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 wid"]. ^The rowi
176a0 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 d is always avai
176b0 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 lable.** as an u
176c0 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e ndeclared column
176d0 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 named ROWID, OI
176e0 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 D, or _ROWID_ as
176f0 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a long as those.*
17700 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 * names are not
17710 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 also used by exp
17720 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 licitly declared
17730 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a columns. ^If.**
17740 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 the table has a
17750 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 column of type
17760 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 [INTEGER PRIMARY
17770 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 KEY] then that
17780 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f column.** is ano
17790 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 ther alias for t
177a0 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 he rowid..**.**
177b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 ^The sqlite3_las
177c0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 t_insert_rowid(D
177d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
177e0 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 rns the [rowid]
177f0 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 of the .** most
17800 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 recent successfu
17810 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 l [INSERT] into
17820 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 a rowid table or
17830 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d [virtual table]
17840 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 .** on database
17850 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a connection D..**
17860 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b ^Inserts into [
17870 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 WITHOUT ROWID] t
17880 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 ables are not re
17890 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e corded..** ^If n
178a0 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e o successful [IN
178b0 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 SERT]s into rowi
178c0 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 d tables.** have
178d0 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f ever occurred o
178e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
178f0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a onnection D, .**
17900 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 then sqlite3_la
17910 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
17920 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e D) returns zero.
17930 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b .**.** ^(If an [
17940 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 INSERT] occurs w
17950 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 ithin a trigger
17960 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 or within a [vir
17970 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d tual table].** m
17980 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 ethod, then this
17990 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 routine will re
179a0 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d turn the [rowid]
179b0 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 of the inserted
179c0 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 .** row as long
179d0 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f as the trigger o
179e0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 r virtual table
179f0 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e method is runnin
17a00 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 g..** But once t
17a10 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 he trigger or vi
17a20 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 rtual table meth
17a30 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c od ends, the val
17a40 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 ue returned .**
17a50 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 by this routine
17a60 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 reverts to what
17a70 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 it was before th
17a80 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 e trigger or vir
17a90 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 tual.** table me
17aa0 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a thod began.)^.**
17ab0 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d .** ^An [INSERT]
17ac0 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 that fails due
17ad0 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 to a constraint
17ae0 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 violation is not
17af0 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c a.** successful
17b00 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f [INSERT] and do
17b10 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
17b20 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
17b30 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 by this.** rout
17b40 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 ine. ^Thus INSE
17b50 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 RT OR FAIL, INSE
17b60 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e RT OR IGNORE, IN
17b70 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b SERT OR ROLLBACK
17b80 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 ,.** and INSERT
17b90 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f OR ABORT make no
17ba0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 changes to the
17bb0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
17bc0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 this.** routine
17bd0 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 when their inser
17be0 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 tion fails. ^(W
17bf0 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 hen INSERT OR RE
17c00 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 PLACE.** encount
17c10 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 ers a constraint
17c20 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 violation, it d
17c30 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 oes not fail. T
17c40 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e he.** INSERT con
17c50 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 tinues to comple
17c60 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 tion after delet
17c70 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 ing rows that ca
17c80 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 used.** the cons
17c90 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 traint problem s
17ca0 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c o INSERT OR REPL
17cb0 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 ACE will always
17cc0 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 change.** the re
17cd0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
17ce0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a is interface.)^.
17cf0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 **.** ^For the p
17d00 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 urposes of this
17d10 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 routine, an [INS
17d20 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 ERT] is consider
17d30 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 ed to.** be succ
17d40 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 essful even if i
17d50 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c t is subsequentl
17d60 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a y rolled back..*
17d70 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
17d80 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 on is accessible
17d90 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e to SQL statemen
17da0 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c ts via the.** [l
17db0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
17dc0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
17dd0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 ..**.** If a sep
17de0 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 arate thread per
17df0 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 forms a new [INS
17e00 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 ERT] on the same
17e10 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
17e20 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 nection while th
17e30 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f e [sqlite3_last_
17e40 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a insert_rowid()].
17e50 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ** function is r
17e60 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 unning and thus
17e70 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 changes the last
17e80 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c insert [rowid],
17e90 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c .** then the val
17ea0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b ue returned by [
17eb0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
17ec0 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a ert_rowid()] is.
17ed0 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 ** unpredictable
17ee0 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 and might not e
17ef0 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 qual either the
17f00 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a old or the new.*
17f10 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 * last insert [r
17f20 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 owid]..*/.SQLITE
17f30 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
17f40 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 64 SQLITE_STDCAL
17f50 4c 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 L sqlite3_last_i
17f60 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 nsert_rowid(sqli
17f70 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
17f80 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 PI3REF: Count Th
17f90 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 e Number Of Rows
17fa0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 Modified.** MET
17fb0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
17fc0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
17fd0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
17fe0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 mber of rows mod
17ff0 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 ified, inserted
18000 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 or.** deleted by
18010 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
18020 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 ly completed INS
18030 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 ERT, UPDATE or D
18040 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 ELETE.** stateme
18050 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 nt on the databa
18060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 se connection sp
18070 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f ecified by the o
18080 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a nly parameter..*
18090 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 * ^Executing any
180a0 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 other type of S
180b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 QL statement doe
180c0 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 s not modify the
180d0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
180e0 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 ed by this funct
180f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 ion..**.** ^Only
18100 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 changes made di
18110 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e rectly by the IN
18120 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 SERT, UPDATE or
18130 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
18140 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 are.** consider
18150 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 ed - auxiliary c
18160 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 hanges caused by
18170 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
18180 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a | triggers], .*
18190 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 * [foreign key a
181a0 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c ctions] or [REPL
181b0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 ACE] constraint
181c0 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e resolution are n
181d0 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a ot counted..** .
181e0 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 ** Changes to a
181f0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e view that are in
18200 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a tercepted by .**
18210 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 [INSTEAD OF tri
18220 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f gger | INSTEAD O
18230 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 F triggers] are
18240 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 not counted. ^Th
18250 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 e value .** retu
18260 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
18270 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 changes() immedi
18280 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 ately after an I
18290 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 NSERT, UPDATE or
182a0 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 .** DELETE stat
182b0 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 ement run on a v
182c0 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 iew is always ze
182d0 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 ro. Only changes
182e0 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a made to real .*
182f0 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 * tables are cou
18300 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e nted..**.** Thin
18310 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 gs are more comp
18320 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 licated if the s
18330 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
18340 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 function is.**
18350 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 executed while a
18360 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d trigger program
18370 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 is running. Thi
18380 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 s may happen if
18390 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 the.** program u
183a0 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 ses the [changes
183b0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
183c0 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 , or if some oth
183d0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 er callback.** f
183e0 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 unction invokes
183f0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
18400 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 ) directly. Esse
18410 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 ntially:.** .**
18420 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e <ul>.** <li> ^
18430 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 (Before entering
18440 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 a trigger progr
18450 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 am the value ret
18460 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 urned by.**
18470 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 sqlite3_chang
18480 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 es() function is
18490 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 saved. After th
184a0 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 e trigger progra
184b0 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 m .** has
184c0 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f finished, the o
184d0 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 riginal value is
184e0 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 restored.)^.**
184f0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 .** <li> ^(Wit
18500 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 hin a trigger pr
18510 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 ogram each INSER
18520 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 T, UPDATE and DE
18530 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 LETE .**
18540 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 statement sets t
18550 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
18560 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 d by sqlite3_cha
18570 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 nges() .**
18580 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f upon completio
18590 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 n as normal. Of
185a0 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c course, this val
185b0 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c ue will not incl
185c0 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 ude .** a
185d0 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f ny changes perfo
185e0 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 rmed by sub-trig
185f0 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c gers, as the sql
18600 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a ite3_changes() .
18610 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 ** value
18620 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e will be saved an
18630 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 d restored after
18640 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 each sub-trigge
18650 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 r has run.)^.**
18660 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 </ul>.** .** ^Th
18670 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 is means that if
18680 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 the changes() S
18690 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 QL function (or
186a0 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 similar) is used
186b0 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 .** by the first
186c0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 INSERT, UPDATE
186d0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d or DELETE statem
186e0 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 ent within a tri
186f0 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 gger, it .** ret
18700 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 urns the value a
18710 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 s set when the c
18720 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 alling statement
18730 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 began executing
18740 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 ..** ^If it is u
18750 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e sed by the secon
18760 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 d or subsequent
18770 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 such statement w
18780 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 ithin a trigger
18790 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 .** program, the
187a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
187b0 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d reflects the num
187c0 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 ber of rows modi
187d0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 fied by the .**
187e0 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c previous INSERT,
187f0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 UPDATE or DELET
18800 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 E statement with
18810 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 in the same trig
18820 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ger..**.** See a
18830 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
18840 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
18850 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 ] interface, the
18860 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 .** [count_chang
18870 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 es pragma], and
18880 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 the [changes() S
18890 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
188a0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
188b0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
188c0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
188d0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
188e0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
188f0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
18900 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
18910 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
18920 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 turned.** is unp
18930 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
18940 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
18950 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
18960 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
18970 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
18980 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
18990 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 * CAPI3REF: Tota
189a0 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 l Number Of Rows
189b0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 Modified.** MET
189c0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
189d0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
189e0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f n returns the to
189f0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f tal number of ro
18a00 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 ws inserted, mod
18a10 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 ified or.** dele
18a20 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 ted by all [INSE
18a30 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 RT], [UPDATE] or
18a40 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d [DELETE] statem
18a50 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a ents completed.*
18a60 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 * since the data
18a70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
18a80 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c was opened, incl
18a90 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 uding those exec
18aa0 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 uted as.** part
18ab0 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 of trigger progr
18ac0 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 ams. ^Executing
18ad0 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f any other type o
18ae0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a f SQL statement.
18af0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 ** does not affe
18b00 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ct the value ret
18b10 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
18b20 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
18b30 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 ..** .** ^Change
18b40 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f s made as part o
18b50 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 f [foreign key a
18b60 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c ctions] are incl
18b70 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 uded in the.** c
18b80 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 ount, but those
18b90 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 made as part of
18ba0 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 REPLACE constrai
18bb0 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 nt resolution ar
18bc0 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 e.** not. ^Chang
18bd0 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 es to a view tha
18be0 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 t are intercepte
18bf0 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 d by INSTEAD OF
18c00 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 triggers .** are
18c10 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a not counted..**
18c20 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 .** See also th
18c30 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 e [sqlite3_chang
18c40 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c es()] interface,
18c50 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 the.** [count_c
18c60 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 hanges pragma],
18c70 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 and the [total_c
18c80 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e hanges() SQL fun
18c90 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 ction]..**.** If
18ca0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
18cb0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 ad makes changes
18cc0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 on the same dat
18cd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18ce0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 .** while [sqlit
18cf0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
18d00 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
18d10 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a hen the value.**
18d20 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 returned is unp
18d30 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
18d40 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
18d50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
18d60 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
18d70 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
18d80 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b anges(sqlite3*);
18d90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
18da0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f : Interrupt A Lo
18db0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 ng-Running Query
18dc0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
18dd0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 te3.**.** ^This
18de0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 function causes
18df0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 any pending data
18e00 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 base operation t
18e10 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 o abort and.** r
18e20 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 eturn at its ear
18e30 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 liest opportunit
18e40 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 y. This routine
18e50 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 is typically.**
18e60 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e called in respon
18e70 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 se to a user act
18e80 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 ion such as pres
18e90 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a sing "Cancel".**
18ea0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 or Ctrl-C where
18eb0 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 the user wants
18ec0 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 a long query ope
18ed0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a ration to halt.*
18ee0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a * immediately..*
18ef0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 *.** ^It is safe
18f00 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f to call this ro
18f10 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 utine from a thr
18f20 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 ead different fr
18f30 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 om the.** thread
18f40 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 that is current
18f50 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 ly running the d
18f60 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f atabase operatio
18f70 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 n. But it.** is
18f80 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c not safe to cal
18f90 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 l this routine w
18fa0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
18fb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 connection] that
18fc0 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 .** is closed or
18fd0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 might close bef
18fe0 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 ore sqlite3_inte
18ff0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e rrupt() returns.
19000 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 .**.** ^If an SQ
19010 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 L operation is v
19020 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 ery nearly finis
19030 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 hed at the time
19040 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f when.** sqlite3_
19050 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 interrupt() is c
19060 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d alled, then it m
19070 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e ight not have an
19080 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 opportunity.**
19090 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 to be interrupte
190a0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 d and might cont
190b0 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 inue to completi
190c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 on..**.** ^An SQ
190d0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 L operation that
190e0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 is interrupted
190f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c will return [SQL
19100 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a ITE_INTERRUPT]..
19110 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 ** ^If the inter
19120 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 rupted SQL opera
19130 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 tion is an INSER
19140 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
19150 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 LETE.** that is
19160 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 inside an explic
19170 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 it transaction,
19180 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 then the entire
19190 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 transaction.** w
191a0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 ill be rolled ba
191b0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ck automatically
191c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
191d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 ite3_interrupt(D
191e0 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 ) call is in eff
191f0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 ect until all cu
19200 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a rrently running.
19210 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
19220 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 s on [database c
19230 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d onnection] D com
19240 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 plete. ^Any new
19250 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
19260 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
19270 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 ted after the sq
19280 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
19290 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 ) call and befor
192a0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e e the .** runnin
192b0 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 g statements rea
192c0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e ches zero are in
192d0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 terrupted as if
192e0 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a they had been.**
192f0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 running prior t
19300 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e o the sqlite3_in
19310 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 terrupt() call.
19320 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d ^New SQL statem
19330 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
19340 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
19350 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 he running state
19360 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 ment count reach
19370 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e es zero are.** n
19380 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 ot effected by t
19390 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
193a0 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 rupt()..** ^A ca
193b0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ll to sqlite3_in
193c0 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 terrupt(D) that
193d0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 occurs when ther
193e0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 e are no running
193f0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
19400 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e ts is a no-op an
19410 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 d has no effect
19420 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 on SQL statement
19430 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
19440 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 arted after the
19450 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
19460 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 t() call returns
19470 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 ..**.** If the d
19480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19490 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 on closes while
194a0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 [sqlite3_interru
194b0 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e pt()].** is runn
194c0 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 ing then bad thi
194d0 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 ngs will likely
194e0 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 happen..*/.SQLIT
194f0 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 E_API void SQLIT
19500 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
19510 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 3_interrupt(sqli
19520 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
19530 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e PI3REF: Determin
19540 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 e If An SQL Stat
19550 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 ement Is Complet
19560 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f e.**.** These ro
19570 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 utines are usefu
19580 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 l during command
19590 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 -line input to d
195a0 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a etermine if the.
195b0 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 ** currently ent
195c0 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 ered text seems
195d0 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 to form a comple
195e0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 te SQL statement
195f0 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 or.** if additi
19600 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 onal input is ne
19610 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 eded before send
19620 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 ing the text int
19630 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 o.** SQLite for
19640 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 parsing. ^These
19650 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
19660 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 1 if the input
19670 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 string.** appear
19680 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 s to be a comple
19690 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 te SQL statement
196a0 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 . ^A statement
196b0 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a is judged to be.
196c0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 ** complete if i
196d0 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 t ends with a se
196e0 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e micolon token an
196f0 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 d is not a prefi
19700 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 x of a.** well-f
19710 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 ormed CREATE TRI
19720 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 GGER statement.
19730 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 ^Semicolons tha
19740 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 t are embedded w
19750 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 ithin.** string
19760 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 literals or quot
19770 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 ed identifier na
19780 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 mes or comments
19790 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 are not.** indep
197a0 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 endent tokens (t
197b0 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 hey are part of
197c0 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 the token in whi
197d0 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 ch they are.** e
197e0 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 mbedded) and thu
197f0 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 s do not count a
19800 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 s a statement te
19810 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 rminator. ^Whit
19820 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f espace.** and co
19830 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c mments that foll
19840 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d ow the final sem
19850 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 icolon are ignor
19860 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 ed..**.** ^These
19870 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
19880 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 0 if the statem
19890 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 ent is incomplet
198a0 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d e. ^If a.** mem
198b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
198c0 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 ails, then SQLIT
198d0 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 E_NOMEM is retur
198e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ned..**.** ^Thes
198f0 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f e routines do no
19900 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 t parse the SQL
19910 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a statements thus.
19920 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 ** will not dete
19930 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 ct syntactically
19940 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a incorrect SQL..
19950 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 **.** ^(If SQLit
19960 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 e has not been i
19970 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 nitialized using
19980 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
19990 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a lize()] prior .*
199a0 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 * to invoking sq
199b0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
199c0 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f () then sqlite3_
199d0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
199e0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d invoked.** autom
199f0 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 atically by sqli
19a00 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
19a10 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 . If that initi
19a20 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c alization fails,
19a30 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 .** then the ret
19a40 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 urn value from s
19a50 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
19a60 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 6() will be non-
19a70 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 zero.** regardle
19a80 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
19a90 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 not the input S
19aa0 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 QL is complete.)
19ab0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 ^.**.** The inpu
19ac0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
19ad0 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 mplete()] must b
19ae0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 e a zero-termina
19af0 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 ted.** UTF-8 str
19b00 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ing..**.** The i
19b10 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 nput to [sqlite3
19b20 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d _complete16()] m
19b30 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 ust be a zero-te
19b40 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d rminated.** UTF-
19b50 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 16 string in nat
19b60 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a ive byte order..
19b70 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
19b80 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
19b90 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
19ba0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 e(const char *sq
19bb0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 l);.SQLITE_API i
19bc0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
19bd0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 L sqlite3_comple
19be0 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 te16(const void
19bf0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 *sql);../*.** CA
19c00 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 PI3REF: Register
19c10 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 A Callback To H
19c20 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 andle SQLITE_BUS
19c30 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 Y Errors.** KEYW
19c40 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 ORDS: {busy-hand
19c50 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 ler callback} {b
19c60 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 usy handler}.**
19c70 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
19c80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
19c90 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
19ca0 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 D,X,P) routine s
19cb0 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ets a callback f
19cc0 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 unction X.** tha
19cd0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b t might be invok
19ce0 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 ed with argument
19cf0 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 P whenever.** a
19d00 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 n attempt is mad
19d10 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 e to access a da
19d20 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 tabase table ass
19d30 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 ociated with.**
19d40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
19d50 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f tion] D when ano
19d60 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f ther thread.** o
19d70 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 r process has th
19d80 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a e table locked..
19d90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 ** The sqlite3_b
19da0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e usy_handler() in
19db0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
19dc0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 to implement.**
19dd0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 [sqlite3_busy_ti
19de0 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 meout()] and [PR
19df0 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 AGMA busy_timeou
19e00 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 t]..**.** ^If th
19e10 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 e busy callback
19e20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 is NULL, then [S
19e30 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 QLITE_BUSY].** i
19e40 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 s returned immed
19e50 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f iately upon enco
19e60 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 untering the loc
19e70 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 k. ^If the busy
19e80 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
19e90 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 not NULL, then t
19ea0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 he callback migh
19eb0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 t be invoked wit
19ec0 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e h two arguments.
19ed0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
19ee0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
19ef0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 e busy handler i
19f00 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
19f10 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 void* pointer wh
19f20 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 ich.** is the th
19f30 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ird argument to
19f40 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
19f50 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 dler(). ^The se
19f60 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
19f70 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e .** the busy han
19f80 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 dler callback is
19f90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 the number of t
19fa0 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 imes that the bu
19fb0 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a sy handler has.*
19fc0 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 * been invoked p
19fd0 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 reviously for th
19fe0 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 e same locking e
19ff0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a vent. ^If the.*
1a000 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 * busy callback
1a010 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 returns 0, then
1a020 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 no additional at
1a030 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 tempts are made
1a040 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 to.** access the
1a050 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 database and [S
1a060 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 QLITE_BUSY] is r
1a070 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 eturned.** to th
1a080 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a e application..*
1a090 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 * ^If the callba
1a0a0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
1a0b0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 ero, then anothe
1a0c0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 r attempt.** is
1a0d0 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 made to access t
1a0e0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 he database and
1a0f0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 the cycle repeat
1a100 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 s..**.** The pre
1a110 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 sence of a busy
1a120 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 handler does not
1a130 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 guarantee that
1a140 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b it will be invok
1a150 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 ed.** when there
1a160 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 is lock content
1a170 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 ion. ^If SQLite
1a180 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 determines that
1a190 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 invoking the bus
1a1a0 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 y.** handler cou
1a1b0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 ld result in a d
1a1c0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c eadlock, it will
1a1d0 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 go ahead and re
1a1e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 turn [SQLITE_BUS
1a1f0 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 Y].** to the app
1a200 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 lication instead
1a210 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 of invoking the
1a220 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 .** busy handle
1a230 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 r..** Consider a
1a240 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 scenario where
1a250 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 one process is h
1a260 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f olding a read lo
1a270 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 ck that.** it is
1a280 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f trying to promo
1a290 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 te to a reserved
1a2a0 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 lock and.** a s
1a2b0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 econd process is
1a2c0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 holding a reser
1a2d0 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 ved lock that it
1a2e0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f is trying.** to
1a2f0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 promote to an e
1a300 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 xclusive lock.
1a310 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 The first proces
1a320 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 s cannot proceed
1a330 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 .** because it i
1a340 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 s blocked by the
1a350 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 second and the
1a360 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 second process c
1a370 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 annot.** proceed
1a380 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 because it is b
1a390 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 locked by the fi
1a3a0 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 rst. If both pr
1a3b0 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b ocesses.** invok
1a3c0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c e the busy handl
1a3d0 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c ers, neither wil
1a3e0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 l make any progr
1a3f0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c ess. Therefore,
1a400 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 .** SQLite retur
1a410 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ns [SQLITE_BUSY]
1a420 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 for the first p
1a430 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 rocess, hoping t
1a440 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c hat this.** will
1a450 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 induce the firs
1a460 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c t process to rel
1a470 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f ease its read lo
1a480 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 ck and allow.**
1a490 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 the second proce
1a4a0 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a ss to proceed..*
1a4b0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c *.** ^The defaul
1a4c0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 t busy callback
1a4d0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e is NULL..**.** ^
1a4e0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 (There can only
1a4f0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 be a single busy
1a500 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 handler defined
1a510 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 for each.** [da
1a520 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1a530 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e n]. Setting a n
1a540 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 ew busy handler
1a550 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 clears any.** pr
1a560 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e eviously set han
1a570 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 dler.)^ ^Note t
1a580 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c hat calling [sql
1a590 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
1a5a0 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 t()].** or evalu
1a5b0 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 ating [PRAGMA bu
1a5c0 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 sy_timeout=N] wi
1a5d0 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a ll change the.**
1a5e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e busy handler an
1a5f0 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 d thus clear any
1a600 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 previously set
1a610 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a busy handler..**
1a620 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c .** The busy cal
1a630 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 lback should not
1a640 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e take any action
1a650 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 s which modify t
1a660 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 he.** database c
1a670 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
1a680 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 nvoked the busy
1a690 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 handler. In oth
1a6a0 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 er words,.** the
1a6b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
1a6c0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 not reentrant.
1a6d0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e Any such action
1a6e0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 s.** result in u
1a6f0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f ndefined behavio
1a700 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 r..** .** A busy
1a710 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f handler must no
1a720 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 t close the data
1a730 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
1a740 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 ** or [prepared
1a750 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
1a760 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 invoked the busy
1a770 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c handler..*/.SQL
1a780 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
1a790 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
1a7a0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
1a7b0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 sqlite3*, int(*)
1a7c0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 (void*,int), voi
1a7d0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
1a7e0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 3REF: Set A Busy
1a7f0 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 Timeout.** METH
1a800 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
1a810 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
1a820 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f sets a [sqlite3_
1a830 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 busy_handler | b
1a840 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 usy handler] tha
1a850 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 t sleeps.** for
1a860 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 a specified amou
1a870 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 nt of time when
1a880 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 a table is locke
1a890 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 d. ^The handler
1a8a0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d .** will sleep m
1a8b0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e ultiple times un
1a8c0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 til at least "ms
1a8d0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f " milliseconds o
1a8e0 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 f sleeping.** ha
1a8f0 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 ve accumulated.
1a900 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 ^After at least
1a910 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
1a920 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a ds of sleeping,.
1a930 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 ** the handler r
1a940 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 eturns 0 which c
1a950 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 auses [sqlite3_s
1a960 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e tep()] to return
1a970 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
1a980 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e ]..**.** ^Callin
1a990 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 g this routine w
1a9a0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 ith an argument
1a9b0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 less than or equ
1a9c0 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 al to zero.** tu
1a9d0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 rns off all busy
1a9e0 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a handlers..**.**
1a9f0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ^(There can onl
1aa00 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
1aa10 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 sy handler for a
1aa20 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b particular.** [
1aa30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1aa40 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 ion] at any give
1aa50 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e n moment. If an
1aa60 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c other busy handl
1aa70 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 er.** was define
1aa80 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 d (using [sqlit
1aa90 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
1aaa0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c )]) prior to cal
1aab0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 ling.** this rou
1aac0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 tine, that other
1aad0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
1aae0 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a cleared.)^.**.*
1aaf0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 * See also: [PR
1ab00 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 AGMA busy_timeou
1ab10 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 t].*/.SQLITE_API
1ab20 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
1ab30 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79 ALL sqlite3_busy
1ab40 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 _timeout(sqlite3
1ab50 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a *, int ms);../*.
1ab60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
1ab70 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 venience Routine
1ab80 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 s For Running Qu
1ab90 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a eries.** METHOD:
1aba0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 sqlite3.**.** T
1abb0 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 his is a legacy
1abc0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 interface that i
1abd0 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 s preserved for
1abe0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
1abf0 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 ibility..** Use
1ac00 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 of this interfac
1ac10 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 e is not recomme
1ac20 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 nded..**.** Defi
1ac30 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 nition: A <b>res
1ac40 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 ult table</b> is
1ac50 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 memory data str
1ac60 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 ucture created b
1ac70 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 y the.** [sqlite
1ac80 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 3_get_table()] i
1ac90 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 nterface. A res
1aca0 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 ult table record
1acb0 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 s the.** complet
1acc0 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 e query results
1acd0 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 from one or more
1ace0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 queries..**.**
1acf0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 The table concep
1ad00 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d tually has a num
1ad10 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 ber of rows and
1ad20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a columns. But.**
1ad30 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 these numbers a
1ad40 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 re not part of t
1ad50 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
1ad60 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a itself. These.*
1ad70 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 * numbers are ob
1ad80 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c tained separatel
1ad90 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 y. Let N be the
1ada0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a number of rows.
1adb0 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 ** and M be the
1adc0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
1add0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c s..**.** A resul
1ade0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 t table is an ar
1adf0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
1ae00 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 to zero-terminat
1ae10 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 ed UTF-8 strings
1ae20 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 ..** There are (
1ae30 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 N+1)*M elements
1ae40 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 in the array. T
1ae50 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 he first M point
1ae60 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 ers point.** to
1ae70 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1ae80 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f strings that co
1ae90 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 ntain the names
1aea0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a of the columns..
1aeb0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 ** The remaining
1aec0 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 entries all poi
1aed0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 nt to query resu
1aee0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 lts. NULL value
1aef0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e s result.** in N
1af00 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 ULL pointers. A
1af10 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 ll other values
1af20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 are in their UTF
1af30 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 -8 zero-terminat
1af40 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 ed.** string rep
1af50 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 resentation as r
1af60 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
1af70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
1af80 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 )]..**.** A resu
1af90 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 lt table might c
1afa0 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 onsist of one or
1afb0 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c more memory all
1afc0 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 ocations..** It
1afd0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 is not safe to p
1afe0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 ass a result tab
1aff0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b le directly to [
1b000 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e sqlite3_free()].
1b010 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 .** A result tab
1b020 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 le should be dea
1b030 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b llocated using [
1b040 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
1b050 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 le()]..**.** ^(A
1b060 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 s an example of
1b070 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
1b080 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 format, suppose
1b090 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a a query result.
1b0a0 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 ** is as follows
1b0b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
1b0c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 ote><pre>.**
1b0d0 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 Name
1b0e0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 | Age.**
1b0f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1b100 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 -------.**
1b110 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 Alice |
1b120 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 43.** Bob
1b130 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a | 28.**
1b140 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 Cindy
1b150 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 | 21.** </pr
1b160 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1b170 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 **.** There are
1b180 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 two column (M==2
1b190 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 ) and three rows
1b1a0 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 (N==3). Thus t
1b1b0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 he.** result tab
1b1c0 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 le has 8 entries
1b1d0 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 . Suppose the r
1b1e0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 esult table is s
1b1f0 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 tored.** in an a
1b200 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 rray names azRes
1b210 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 ult. Then azRes
1b220 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 ult holds this c
1b230 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ontent:.**.** <b
1b240 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1b250 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1b260 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d lt[0] = "Nam
1b270 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
1b280 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 Result[1] =
1b290 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 "Age";.**
1b2a0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d azResult[2]
1b2b0 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 = "Alice";.**
1b2c0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1b2d0 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 91;3] = "43";.**
1b2e0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1b2f0 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b [4] = "Bob";
1b300 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1b310 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 ult[5] = "28
1b320 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1b330 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 esult[6] = "
1b340 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 Cindy";.**
1b350 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 azResult[7
1b360 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 ] = "21";.** </p
1b370 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1b380 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 )^.**.** ^The sq
1b390 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1b3a0 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 ) function evalu
1b3b0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 ates one or more
1b3c0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 .** semicolon-se
1b3d0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 parated SQL stat
1b3e0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 ements in the ze
1b3f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
1b400 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 F-8.** string of
1b410 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 its 2nd paramet
1b420 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 er and returns a
1b430 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f result table to
1b440 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 the.** pointer
1b450 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 given in its 3rd
1b460 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
1b470 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c * After the appl
1b480 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 ication has fini
1b490 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 shed with the re
1b4a0 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 sult from sqlite
1b4b0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 3_get_table(),.*
1b4c0 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 * it must pass t
1b4d0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
1b4e0 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 pointer to sqlit
1b4f0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 e3_free_table()
1b500 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 in order to.** r
1b510 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 elease the memor
1b520 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f y that was mallo
1b530 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 ced. Because of
1b540 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 the way the.**
1b550 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1b560 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 )] happens withi
1b570 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 n sqlite3_get_ta
1b580 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 ble(), the calli
1b590 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d ng.** function m
1b5a0 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 ust not try to c
1b5b0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 all [sqlite3_fre
1b5c0 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 e()] directly.
1b5d0 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 Only.** [sqlite3
1b5e0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 _free_table()] i
1b5f0 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 s able to releas
1b600 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f e the memory pro
1b610 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 perly and safely
1b620 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
1b630 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
1b640 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 interface is imp
1b650 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 lemented as a wr
1b660 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 apper around.**
1b670 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
1b680 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 . The sqlite3_g
1b690 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 et_table() routi
1b6a0 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 ne does not have
1b6b0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e access.** to an
1b6c0 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 y internal data
1b6d0 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 structures of SQ
1b6e0 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f Lite. It uses o
1b6f0 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a nly the public.*
1b700 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 * interface defi
1b710 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 ned here. As a
1b720 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 consequence, err
1b730 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 ors that occur i
1b740 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 n the.** wrapper
1b750 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f layer outside o
1b760 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b f the internal [
1b770 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
1b780 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 call are not.**
1b790 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 reflected in sub
1b7a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
1b7b0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
1b7c0 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 e()] or.** [sqli
1b7d0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a te3_errmsg()]..*
1b7e0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
1b7f0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
1b800 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
1b810 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 e(. sqlite3 *db
1b820 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e , /* An
1b830 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a open database *
1b840 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
1b850 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c zSql, /* SQL
1b860 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 to be evaluated
1b870 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 */. char ***pa
1b880 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 zResult, /* R
1b890 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 esults of the qu
1b8a0 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e ery */. int *pn
1b8b0 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f Row, /
1b8c0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 * Number of resu
1b8d0 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 lt rows written
1b8e0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 here */. int *p
1b8f0 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 nColumn,
1b900 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 /* Number of res
1b910 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 ult columns writ
1b920 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 ten here */. ch
1b930 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 ar **pzErrmsg
1b940 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 /* Error msg
1b950 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
1b960 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .);.SQLITE_API v
1b970 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 oid SQLITE_STDCA
1b980 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f LL sqlite3_free_
1b990 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 table(char **res
1b9a0 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ult);../*.** CAP
1b9b0 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 I3REF: Formatted
1b9c0 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 String Printing
1b9d0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a Functions.**.**
1b9e0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1b9f0 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 are work-alikes
1ba00 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 of the "printf()
1ba10 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 " family of func
1ba20 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 tions.** from th
1ba30 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
1ba40 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 rary..** These r
1ba50 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 outines understa
1ba60 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 nd most of the c
1ba70 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 ommon K&R format
1ba80 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a ting options,.**
1ba90 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 plus some addit
1baa0 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 ional non-standa
1bab0 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 rd formats, deta
1bac0 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e iled below..** N
1bad0 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 ote that some of
1bae0 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 the more obscur
1baf0 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 e formatting opt
1bb00 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 ions from recent
1bb10 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 .** C-library st
1bb20 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 andards are omit
1bb30 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d ted from this im
1bb40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a plementation..**
1bb50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1bb60 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 _mprintf() and s
1bb70 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
1bb80 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 ) routines write
1bb90 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 their.** result
1bba0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 s into memory ob
1bbb0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
1bbc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a ite3_malloc()]..
1bbd0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 ** The strings r
1bbe0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
1bbf0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 two routines sh
1bc00 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 ould be.** relea
1bc10 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
1bc20 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 free()]. ^Both
1bc30 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
1bc40 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
1bc50 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
1bc60 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
1bc70 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
1bc80 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
1bc90 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
1bca0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
1bcb0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
1bcc0 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 _snprintf() rout
1bcd0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ine is similar t
1bce0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 o "snprintf()" f
1bcf0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 rom.** the stand
1bd00 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 ard C library.
1bd10 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 The result is wr
1bd20 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a itten into the.*
1bd30 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 * buffer supplie
1bd40 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
1bd50 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 parameter whose
1bd60 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 size is given by
1bd70 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 .** the first pa
1bd80 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 rameter. Note th
1bd90 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 at the order of
1bda0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f the.** first two
1bdb0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 parameters is r
1bdc0 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 eversed from snp
1bdd0 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 rintf().)^ This
1bde0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 is an.** histor
1bdf0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 ical accident th
1be00 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 at cannot be fix
1be10 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ed without break
1be20 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 ing.** backwards
1be30 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 compatibility.
1be40 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 ^(Note also tha
1be50 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e t sqlite3_snprin
1be60 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 tf().** returns
1be70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 a pointer to its
1be80 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 buffer instead
1be90 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 of the number of
1bea0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 .** characters a
1beb0 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 ctually written
1bec0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e into the buffer.
1bed0 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 )^ We admit tha
1bee0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 t.** the number
1bef0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 of characters wr
1bf00 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 itten would be a
1bf10 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 more useful ret
1bf20 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 urn.** value but
1bf30 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 we cannot chang
1bf40 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 e the implementa
1bf50 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
1bf60 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f snprintf().** no
1bf70 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 w without breaki
1bf80 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ng compatibility
1bf90 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 ..**.** ^As long
1bfa0 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 as the buffer s
1bfb0 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 ize is greater t
1bfc0 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 han zero, sqlite
1bfd0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
1bfe0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 guarantees that
1bff0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c the buffer is al
1c000 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e ways zero-termin
1c010 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 ated. ^The firs
1c020 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 t.** parameter "
1c030 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 n" is the total
1c040 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 size of the buff
1c050 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 er, including sp
1c060 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a ace for.** the z
1c070 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero terminator.
1c080 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 So the longest
1c090 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 string that can
1c0a0 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a be completely.**
1c0b0 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 written will be
1c0c0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e n-1 characters.
1c0d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1c0e0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 te3_vsnprintf()
1c0f0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 routine is a var
1c100 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 args version of
1c110 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1c120 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ()..**.** These
1c130 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 routines all imp
1c140 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 lement some addi
1c150 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e tional formattin
1c160 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 g.** options tha
1c170 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 t are useful for
1c180 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 constructing SQ
1c190 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
1c1a0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 All of the usua
1c1b0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 l printf() forma
1c1c0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 tting options ap
1c1d0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f ply. In additio
1c1e0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 n, there.** is a
1c1f0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 re "%q", "%Q", "
1c200 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 %w" and "%z" opt
1c210 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ions..**.** ^(Th
1c220 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b e %q option work
1c230 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 s like %s in tha
1c240 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 t it substitutes
1c250 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 a nul-terminate
1c260 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d d.** string from
1c270 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 the argument li
1c280 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f st. But %q also
1c290 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 doubles every '
1c2a0 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a \'' character..*
1c2b0 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 * %q is designed
1c2c0 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 for use inside
1c2d0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c a string literal
1c2e0 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 .)^ By doubling
1c2f0 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 each '\''.** ch
1c300 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 aracter it escap
1c310 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 es that characte
1c320 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 r and allows it
1c330 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 to be inserted i
1c340 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e nto.** the strin
1c350 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 g..**.** For exa
1c360 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 mple, assume the
1c370 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 string variable
1c380 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 zText contains
1c390 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a text as follows:
1c3a0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1c3b0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 te><pre>.** cha
1c3c0 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 r *zText = "It's
1c3d0 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a a happy day!";.
1c3e0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1c3f0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 quote>.**.** One
1c400 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 can use this te
1c410 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 xt in an SQL sta
1c420 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 tement as follow
1c430 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
1c440 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
1c450 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
1c460 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
1c470 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
1c480 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 ALUES('%q')", zT
1c490 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 ext);.** sqlite
1c4a0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 3_exec(db, zSQL,
1c4b0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 0, 0, 0);.** s
1c4c0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c qlite3_free(zSQL
1c4d0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
1c4e0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
1c4f0 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 Because the %q f
1c500 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 ormat string is
1c510 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 used, the '\'' c
1c520 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 haracter in zTex
1c530 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 t.** is escaped
1c540 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 and the SQL gene
1c550 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c rated is as foll
1c560 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
1c570 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
1c580 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 INSERT INTO tab
1c590 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 le1 VALUES('It''
1c5a0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 s a happy day!')
1c5b0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1c5c0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
1c5d0 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 is is correct.
1c5e0 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 Had we used %s i
1c5f0 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 nstead of %q, th
1c600 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a e generated SQL.
1c610 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f ** would have lo
1c620 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a oked like this:.
1c630 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1c640 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 e><pre>.** INSE
1c650 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 RT INTO table1 V
1c660 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 ALUES('It's a ha
1c670 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c ppy day!');.** <
1c680 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1c690 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 e>.**.** This se
1c6a0 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 cond example is
1c6b0 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 an SQL syntax er
1c6c0 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 ror. As a gener
1c6d0 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 al rule you shou
1c6e0 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 ld.** always use
1c6f0 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 %q instead of %
1c700 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 s when inserting
1c710 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 text into a str
1c720 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a ing literal..**.
1c730 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 ** ^(The %Q opti
1c740 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 on works like %q
1c750 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 except it also
1c760 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 adds single quot
1c770 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 es around.** the
1c780 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 outside of the
1c790 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 total string. A
1c7a0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 dditionally, if
1c7b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e the parameter in
1c7c0 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 the.** argument
1c7d0 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 list is a NULL
1c7e0 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 pointer, %Q subs
1c7f0 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 titutes the text
1c800 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 "NULL" (without
1c810 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 .** single quote
1c820 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 s).)^ So, for e
1c830 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c xample, one coul
1c840 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c d say:.**.** <bl
1c850 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1c860 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 * char *zSQL =
1c870 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1c880 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 "INSERT INTO tab
1c890 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 le VALUES(%Q)",
1c8a0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 zText);.** sqli
1c8b0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 te3_exec(db, zSQ
1c8c0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 L, 0, 0, 0);.**
1c8d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 sqlite3_free(zS
1c8e0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f QL);.** </pre></
1c8f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
1c900 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 * The code above
1c910 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 will render a c
1c920 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 orrect SQL state
1c930 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c ment in the zSQL
1c940 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 .** variable eve
1c950 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 n if the zText v
1c960 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c ariable is a NUL
1c970 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
1c980 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d ^(The "%w" form
1c990 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 atting option is
1c9a0 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 like "%q" excep
1c9b0 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 t that it expect
1c9c0 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 s to.** be conta
1c9d0 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 ined within doub
1c9e0 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 le-quotes instea
1c9f0 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 d of single quot
1ca00 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 es, and it.** es
1ca10 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 capes the double
1ca20 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 -quote character
1ca30 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
1ca40 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 single-quote.**
1ca50 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 character.)^ Th
1ca60 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e e "%w" formattin
1ca70 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 g option is inte
1ca80 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 nded for safely
1ca90 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 inserting.** tab
1caa0 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 le and column na
1cab0 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 mes into a const
1cac0 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 ructed SQL state
1cad0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ment..**.** ^(Th
1cae0 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e e "%z" formattin
1caf0 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c g option works l
1cb00 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 ike "%s" but wit
1cb10 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f h the.** additio
1cb20 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 n that after the
1cb30 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e string has been
1cb40 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 read and copied
1cb50 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 into.** the res
1cb60 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 ult, [sqlite3_fr
1cb70 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 ee()] is called
1cb80 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 on the input str
1cb90 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 ing.)^.*/.SQLITE
1cba0 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 _API char *SQLIT
1cbb0 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f E_CDECL sqlite3_
1cbc0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
1cbd0 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 ar*,...);.SQLITE
1cbe0 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 _API char *SQLIT
1cbf0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
1cc00 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 3_vmprintf(const
1cc10 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 char*, va_list)
1cc20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 ;.SQLITE_API cha
1cc30 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 r *SQLITE_CDECL
1cc40 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1cc50 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 (int,char*,const
1cc60 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 char*, ...);.SQ
1cc70 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 LITE_API char *S
1cc80 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
1cc90 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 lite3_vsnprintf(
1cca0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 int,char*,const
1ccb0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b char*, va_list);
1ccc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1ccd0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
1cce0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a ion Subsystem.**
1ccf0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
1cd00 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 ore uses these t
1cd10 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hree routines fo
1cd20 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e r all of its own
1cd30 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d .** internal mem
1cd40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
1cd50 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 eeds. "Core" in
1cd60 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e the previous sen
1cd70 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f tence.** does no
1cd80 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 t include operat
1cd90 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
1cda0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e fic VFS implemen
1cdb0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 tation. The.**
1cdc0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 Windows VFS uses
1cdd0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 native malloc()
1cde0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 and free() for
1cdf0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e some operations.
1ce00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1ce10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 te3_malloc() rou
1ce20 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
1ce30 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 ointer to a bloc
1ce40 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 k.** of memory a
1ce50 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
1ce60 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 in length, where
1ce70 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 N is the parame
1ce80 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ter..** ^If sqli
1ce90 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 te3_malloc() is
1cea0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e unable to obtain
1ceb0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 sufficient free
1cec0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 .** memory, it r
1ced0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
1cee0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 inter. ^If the
1cef0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a parameter N to.*
1cf00 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
1cf10 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 () is zero or ne
1cf20 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 gative then sqli
1cf30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 te3_malloc() ret
1cf40 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 urns.** a NULL p
1cf50 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ointer..**.** ^T
1cf60 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f he sqlite3_mallo
1cf70 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 c64(N) routine w
1cf80 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a orks just like.*
1cf90 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
1cfa0 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 (N) except that
1cfb0 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 N is an unsigned
1cfc0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
1cfd0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 instead.** of a
1cfe0 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e signed 32-bit in
1cff0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 teger..**.** ^Ca
1d000 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 lling sqlite3_fr
1d010 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e ee() with a poin
1d020 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 ter previously r
1d030 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 eturned.** by sq
1d040 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f lite3_malloc() o
1d050 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
1d060 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 c() releases tha
1d070 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 t memory so.** t
1d080 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 hat it might be
1d090 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 reused. ^The sq
1d0a0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 lite3_free() rou
1d0b0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d tine is.** a no-
1d0c0 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 op if is called
1d0d0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
1d0e0 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 ter. Passing a
1d0f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
1d100 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 to sqlite3_free(
1d110 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 ) is harmless.
1d120 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 After being free
1d130 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f d, memory.** sho
1d140 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 uld neither be r
1d150 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e ead nor written.
1d160 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 Even reading p
1d170 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a reviously freed.
1d180 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 ** memory might
1d190 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d result in a segm
1d1a0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f entation fault o
1d1b0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 r other severe e
1d1c0 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 rror..** Memory
1d1d0 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 corruption, a se
1d1e0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 gmentation fault
1d1f0 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 , or other sever
1d200 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 e error.** might
1d210 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 result if sqlit
1d220 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c e3_free() is cal
1d230 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e led with a non-N
1d240 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ULL pointer that
1d250 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 .** was not obta
1d260 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
1d270 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 3_malloc() or sq
1d280 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e lite3_realloc().
1d290 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1d2a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1d2b0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
1d2c0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a pts to resize a.
1d2d0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 ** prior memory
1d2e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 allocation X to
1d2f0 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 be at least N by
1d300 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 tes..** ^If the
1d310 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 X parameter to s
1d320 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
1d330 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c ,N).** is a NULL
1d340 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 pointer then it
1d350 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 s behavior is id
1d360 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 entical to calli
1d370 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 ng.** sqlite3_ma
1d380 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 lloc(N)..** ^If
1d390 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 the N parameter
1d3a0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
1d3b0 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 oc(X,N) is zero
1d3c0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 or.** negative t
1d3d0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
1d3e0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 is exactly the
1d3f0 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a same as calling.
1d400 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 ** sqlite3_free(
1d410 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f X)..** ^sqlite3_
1d420 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 realloc(X,N) ret
1d430 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
1d440 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 o a memory alloc
1d450 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c ation.** of at l
1d460 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 east N bytes in
1d470 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 size or NULL if
1d480 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d insufficient mem
1d490 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 ory is available
1d4a0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 ..** ^If M is th
1d4b0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 e size of the pr
1d4c0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 ior allocation,
1d4d0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 then min(N,M) by
1d4e0 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 tes.** of the pr
1d4f0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 ior allocation a
1d500 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 re copied into t
1d510 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
1d520 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a buffer returned.
1d530 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 ** by sqlite3_re
1d540 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 alloc(X,N) and t
1d550 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
1d560 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a ion is freed..**
1d570 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 ^If sqlite3_rea
1d580 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e lloc(X,N) return
1d590 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 s NULL and N is
1d5a0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 positive, then t
1d5b0 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f he.** prior allo
1d5c0 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 cation is not fr
1d5d0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 eed..**.** ^The
1d5e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 sqlite3_realloc6
1d5f0 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 4(X,N) interface
1d600 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 s works the same
1d610 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 as.** sqlite3_r
1d620 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 ealloc(X,N) exce
1d630 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 pt that N is a 6
1d640 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 4-bit unsigned i
1d650 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a nteger instead.*
1d660 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 * of a 32-bit si
1d670 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a gned integer..**
1d680 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d .** ^If X is a m
1d690 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1d6a0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 previously obta
1d6b0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
1d6c0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 3_malloc(),.** s
1d6d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 qlite3_malloc64(
1d6e0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c ), sqlite3_reall
1d6f0 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 oc(), or sqlite3
1d700 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 _realloc64(), th
1d710 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 en.** sqlite3_ms
1d720 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 ize(X) returns t
1d730 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 he size of that
1d740 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1d750 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e n in bytes..** ^
1d760 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e The value return
1d770 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 ed by sqlite3_ms
1d780 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 ize(X) might be
1d790 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 larger than the
1d7a0 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 number.** of byt
1d7b0 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 es requested whe
1d7c0 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 n X was allocate
1d7d0 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e d. ^If X is a N
1d7e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
1d7f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a .** sqlite3_msiz
1d800 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 e(X) returns zer
1d810 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 o. If X points
1d820 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 to something tha
1d830 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 t is not.** the
1d840 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d beginning of mem
1d850 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 ory allocation,
1d860 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 or if it points
1d870 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a to a formerly.**
1d880 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c valid memory al
1d890 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 location that ha
1d8a0 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 s now been freed
1d8b0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
1d8c0 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 ior.** of sqlite
1d8d0 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 3_msize(X) is un
1d8e0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 defined and poss
1d8f0 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a ibly harmful..**
1d900 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 .** ^The memory
1d910 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
1d920 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 te3_malloc(), sq
1d930 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c lite3_realloc(),
1d940 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c .** sqlite3_mall
1d950 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 oc64(), and sqli
1d960 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a te3_realloc64().
1d970 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 ** is always ali
1d980 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 gned to at least
1d990 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 an 8 byte bound
1d9a0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 ary, or to a.**
1d9b0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 4 byte boundary
1d9c0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 if the [SQLITE_4
1d9d0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 _BYTE_ALIGNED_MA
1d9e0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 LLOC] compile-ti
1d9f0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 me.** option is
1da00 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 used..**.** In S
1da10 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
1da20 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 5.0 and 3.5.1, i
1da30 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 t was possible t
1da40 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 o define.** the
1da50 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f SQLITE_OMIT_MEMO
1da60 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 RY_ALLOCATION wh
1da70 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 ich would cause
1da80 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 the built-in.**
1da90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
1daa0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
1dab0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 to be omitted.
1dac0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 That capability
1dad0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 .** is no longer
1dae0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 provided. Only
1daf0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
1db00 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 allocators can
1db10 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 be used..**.** P
1db20 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 rior to SQLite v
1db30 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 ersion 3.7.10, t
1db40 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e he Windows OS in
1db50 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 terface layer ca
1db60 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 lled.** the syst
1db70 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 em malloc() and
1db80 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 free() directly
1db90 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a when converting.
1dba0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 ** filenames bet
1dbb0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 ween the UTF-8 e
1dbc0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 ncoding used by
1dbd0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 SQLite.** and wh
1dbe0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 atever filename
1dbf0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 encoding is used
1dc00 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c by the particul
1dc10 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e ar Windows.** in
1dc20 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d stallation. Mem
1dc30 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
1dc40 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 rrors were detec
1dc50 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 ted, but.** they
1dc60 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 were reported b
1dc70 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 ack as [SQLITE_C
1dc80 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b ANTOPEN] or.** [
1dc90 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 SQLITE_IOERR] ra
1dca0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
1dcb0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 E_NOMEM]..**.**
1dcc0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 The pointer argu
1dcd0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 ments to [sqlite
1dce0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 3_free()] and [s
1dcf0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1dd00 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 ].** must be eit
1dd10 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 her NULL or else
1dd20 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e pointers obtain
1dd30 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a ed from a prior.
1dd40 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ** invocation of
1dd50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1dd60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1dd70 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 realloc()] that
1dd80 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 have.** not yet
1dd90 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a been released..*
1dda0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
1ddb0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 tion must not re
1ddc0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 ad or write any
1ddd0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f part of.** a blo
1dde0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 ck of memory aft
1ddf0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 er it has been r
1de00 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a eleased using.**
1de10 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1de20 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
1de30 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c alloc()]..*/.SQL
1de40 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 ITE_API void *SQ
1de50 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1de60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 ite3_malloc(int)
1de70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
1de80 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
1de90 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 L sqlite3_malloc
1dea0 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 64(sqlite3_uint6
1deb0 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 4);.SQLITE_API v
1dec0 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 oid *SQLITE_STDC
1ded0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c ALL sqlite3_real
1dee0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b loc(void*, int);
1def0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
1df00 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
1df10 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1df20 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 64(void*, sqlite
1df30 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 3_uint64);.SQLIT
1df40 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 E_API void SQLIT
1df50 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
1df60 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 3_free(void*);.S
1df70 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
1df80 33 5f 75 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 3_uint64 SQLITE_
1df90 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
1dfa0 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f msize(void*);../
1dfb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
1dfc0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 emory Allocator
1dfd0 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a Statistics.**.**
1dfe0 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 SQLite provides
1dff0 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 these two inter
1e000 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 faces for report
1e010 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 ing on the statu
1e020 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c s.** of the [sql
1e030 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 ite3_malloc()],
1e040 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1e050 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 , and [sqlite3_r
1e060 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 ealloc()].** rou
1e070 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 tines, which for
1e080 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d m the built-in m
1e090 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1e0a0 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a subsystem..**.*
1e0b0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
1e0c0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 memory_used()] r
1e0d0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
1e0e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
1e0f0 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 es.** of memory
1e100 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 currently outsta
1e110 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 nding (malloced
1e120 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a but not freed)..
1e130 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
1e140 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
1e150 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 r()] routine ret
1e160 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d urns the maximum
1e170 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 .** value of [sq
1e180 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
1e190 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 d()] since the h
1e1a0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
1e1b0 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 * was last reset
1e1c0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 . ^The values r
1e1d0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
1e1e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
1e1f0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
1e200 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
1e210 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 ter()] include a
1e220 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 ny overhead.** a
1e230 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 dded by SQLite i
1e240 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 n its implementa
1e250 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
1e260 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 _malloc()],.** b
1e270 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 ut not overhead
1e280 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 added by the any
1e290 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 underlying syst
1e2a0 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f em library.** ro
1e2b0 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c utines that [sql
1e2c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d ite3_malloc()] m
1e2d0 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e ay call..**.** ^
1e2e0 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d The memory high-
1e2f0 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 water mark is re
1e300 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 set to the curre
1e310 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b nt value of.** [
1e320 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
1e330 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e sed()] if and on
1e340 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 ly if the parame
1e350 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ter to.** [sqlit
1e360 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
1e370 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 ter()] is true.
1e380 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 ^The value retu
1e390 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 rned.** by [sqli
1e3a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
1e3b0 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 ater(1)] is the
1e3c0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a high-water mark.
1e3d0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 ** prior to the
1e3e0 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 reset..*/.SQLITE
1e3f0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
1e400 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 64 SQLITE_STDCAL
1e410 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 L sqlite3_memory
1e420 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c _used(void);.SQL
1e430 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
1e440 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 int64 SQLITE_STD
1e450 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d CALL sqlite3_mem
1e460 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e ory_highwater(in
1e470 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f t resetFlag);../
1e480 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 *.** CAPI3REF: P
1e490 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d seudo-Random Num
1e4a0 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a ber Generator.**
1e4b0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 .** SQLite conta
1e4c0 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 ins a high-quali
1e4d0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d ty pseudo-random
1e4e0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f number generato
1e4f0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f r (PRNG) used to
1e500 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f .** select rando
1e510 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 m [ROWID | ROWID
1e520 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e s] when insertin
1e530 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e g new records in
1e540 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a to a table that.
1e550 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 ** already uses
1e560 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 the largest poss
1e570 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 ible [ROWID]. T
1e580 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 he PRNG is also
1e590 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 used for.** the
1e5a0 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 build-in random(
1e5b0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 ) and randomblob
1e5c0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 () SQL functions
1e5d0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 . This interfac
1e5e0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c e allows.** appl
1e5f0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 ications to acce
1e600 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 ss the same PRNG
1e610 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f for other purpo
1e620 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 ses..**.** ^A ca
1e630 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 ll to this routi
1e640 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 ne stores N byte
1e650 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 s of randomness
1e660 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a into buffer P..*
1e670 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 * ^The P paramet
1e680 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c er can be a NULL
1e690 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
1e6a0 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ^If this routine
1e6b0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 has not been pr
1e6c0 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 eviously called
1e6d0 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f or if the previo
1e6e0 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e us.** call had N
1e6f0 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f less than one o
1e700 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
1e710 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 for P, then the
1e720 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 PRNG is.** seed
1e730 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e ed using randomn
1e740 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ess obtained fro
1e750 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 m the xRandomnes
1e760 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 s method of.** t
1e770 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
1e780 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
1e790 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 .** ^If the prev
1e7a0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 ious call to thi
1e7b0 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e s routine had an
1e7c0 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 N of 1 or more
1e7d0 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c and a.** non-NUL
1e7e0 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 L P then the pse
1e7f0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 udo-randomness i
1e800 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 s generated.** i
1e810 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 nternally and wi
1e820 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 thout recourse t
1e830 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
1e840 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a fs] xRandomness.
1e850 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 ** method..*/.SQ
1e860 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 LITE_API void SQ
1e870 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1e880 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 ite3_randomness(
1e890 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b int N, void *P);
1e8a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1e8b0 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 : Compile-Time A
1e8c0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c uthorization Cal
1e8d0 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 lbacks.** METHOD
1e8e0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
1e8f0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 ^This routine re
1e900 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f gisters an autho
1e910 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 rizer callback w
1e920 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 ith a particular
1e930 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
1e940 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c nnection], suppl
1e950 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 ied in the first
1e960 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 argument..** ^T
1e970 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
1e980 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
1e990 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 d as SQL stateme
1e9a0 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f nts are being co
1e9b0 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 mpiled.** by [sq
1e9c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
1e9d0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
1e9e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1e9f0 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c e_v2()],.** [sql
1ea00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
1ea10 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
1ea20 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 repare16_v2()].
1ea30 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 ^At various.**
1ea40 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 points during th
1ea50 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 e compilation pr
1ea60 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 ocess, as logic
1ea70 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 is being created
1ea80 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 .** to perform v
1ea90 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 arious actions,
1eaa0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
1eab0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
1eac0 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 ed to.** see if
1ead0 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 those actions ar
1eae0 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 e allowed. ^The
1eaf0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1eb00 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 back should.** r
1eb10 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
1eb20 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 ] to allow the a
1eb30 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 ction, [SQLITE_I
1eb40 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c GNORE] to disall
1eb50 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 ow the.** specif
1eb60 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c ic action but al
1eb70 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 low the SQL stat
1eb80 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 ement to continu
1eb90 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 e to be.** compi
1eba0 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f led, or [SQLITE_
1ebb0 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 DENY] to cause t
1ebc0 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 he entire SQL st
1ebd0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a atement to be.**
1ebe0 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 rejected with a
1ebf0 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 n error. ^If th
1ec00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1ec10 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a lback returns.**
1ec20 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 any value other
1ec30 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 than [SQLITE_IG
1ec40 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f NORE], [SQLITE_O
1ec50 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 K], or [SQLITE_D
1ec60 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ENY].** then the
1ec70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1ec80 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 e_v2()] or equiv
1ec90 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 alent call that
1eca0 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 triggered.** the
1ecb0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c authorizer will
1ecc0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 fail with an er
1ecd0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a ror message..**.
1ece0 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c ** When the call
1ecf0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
1ed00 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d LITE_OK], that m
1ed10 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 eans the operati
1ed20 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 on.** requested
1ed30 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 is ok. ^When th
1ed40 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
1ed50 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d ns [SQLITE_DENY]
1ed60 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 , the.** [sqlite
1ed70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1ed80 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 or equivalent ca
1ed90 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 ll that triggere
1eda0 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 d the.** authori
1edb0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 zer will fail wi
1edc0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 th an error mess
1edd0 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 age explaining t
1ede0 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 hat.** access is
1edf0 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 denied. .**.**
1ee00 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d ^The first param
1ee10 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 eter to the auth
1ee20 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1ee30 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
1ee40 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 third.** parame
1ee50 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
1ee60 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1ee70 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e r() interface. ^
1ee80 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
1ee90 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 eter.** to the c
1eea0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e allback is an in
1eeb0 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f teger [SQLITE_CO
1eec0 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 PY | action code
1eed0 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 ] that specifies
1eee0 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c .** the particul
1eef0 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 ar action to be
1ef00 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 authorized. ^The
1ef10 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 third through s
1ef20 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a ixth parameters.
1ef30 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 ** to the callba
1ef40 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d ck are zero-term
1ef50 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 inated strings t
1ef60 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 hat contain addi
1ef70 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c tional.** detail
1ef80 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 s about the acti
1ef90 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 on to be authori
1efa0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 zed..**.** ^If t
1efb0 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 he action code i
1efc0 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a s [SQLITE_READ].
1efd0 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 ** and the callb
1efe0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
1eff0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e ITE_IGNORE] then
1f000 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
1f010 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 d statement] sta
1f020 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 tement is constr
1f030 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 ucted to substit
1f040 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 ute.** a NULL va
1f050 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 lue in place of
1f060 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e the table column
1f070 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 that would have
1f080 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 .** been read if
1f090 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 [SQLITE_OK] had
1f0a0 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 been returned.
1f0b0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e The [SQLITE_IGN
1f0c0 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 ORE].** return c
1f0d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 an be used to de
1f0e0 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 ny an untrusted
1f0f0 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 user access to i
1f100 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c ndividual.** col
1f110 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e umns of a table.
1f120 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 .** ^If the acti
1f130 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 on code is [SQLI
1f140 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 TE_DELETE] and t
1f150 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
1f160 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 rns.** [SQLITE_I
1f170 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 GNORE] then the
1f180 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 [DELETE] operati
1f190 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 on proceeds but
1f1a0 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 the.** [truncate
1f1b0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 optimization] i
1f1c0 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 s disabled and a
1f1d0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 ll rows are dele
1f1e0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 ted individually
1f1f0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f ..**.** An autho
1f200 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 rizer is used wh
1f210 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 en [sqlite3_prep
1f220 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d are | preparing]
1f230 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
1f240 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 ts from an untru
1f250 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 sted source, to
1f260 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 ensure that the
1f270 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
1f280 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 * do not try to
1f290 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 access data they
1f2a0 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 are not allowed
1f2b0 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 to see, or that
1f2c0 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 they do not.**
1f2d0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d try to execute m
1f2e0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 alicious stateme
1f2f0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 nts that damage
1f300 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 the database. F
1f310 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 or.** example, a
1f320 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 n application ma
1f330 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 y allow a user t
1f340 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 o enter arbitrar
1f350 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 y.** SQL queries
1f360 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 for evaluation
1f370 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 by a database.
1f380 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 But the applicat
1f390 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 ion does.** not
1f3a0 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f want the user to
1f3b0 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 be able to make
1f3c0 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 arbitrary chang
1f3d0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 es to the.** dat
1f3e0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f abase. An autho
1f3f0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e rizer could then
1f400 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 be put in place
1f410 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 while the.** us
1f420 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 er-entered SQL i
1f430 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 s being [sqlite3
1f440 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
1f450 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 red] that.** dis
1f460 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e allows everythin
1f470 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 g except [SELECT
1f480 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a ] statements..**
1f490 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 .** Applications
1f4a0 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 that need to pr
1f4b0 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 ocess SQL from u
1f4c0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 ntrusted sources
1f4d0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 .** might also c
1f4e0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 onsider lowering
1f4f0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 resource limits
1f500 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
1f510 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 limit()].** and
1f520 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 limiting databas
1f530 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 e size using the
1f540 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 [max_page_count
1f550 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e ] [PRAGMA].** in
1f560 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 addition to usi
1f570 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 ng an authorizer
1f580 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 ..**.** ^(Only a
1f590 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a single authoriz
1f5a0 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 er can be in pla
1f5b0 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 ce on a database
1f5c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 connection.** a
1f5d0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 t a time. Each
1f5e0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
1f5f0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f set_authorizer o
1f600 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 verrides the.**
1f610 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e previous call.)^
1f620 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 ^Disable the a
1f630 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 uthorizer by ins
1f640 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 talling a NULL c
1f650 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 allback..** The
1f660 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 authorizer is di
1f670 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
1f680 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 t..**.** The aut
1f690 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1f6a0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 must not do any
1f6b0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 thing that will
1f6c0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 modify.** the da
1f6d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1f6e0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
1f6f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
1f700 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 llback..** Note
1f710 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
1f720 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
1f730 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1f740 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
1f750 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
1f760 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
1f770 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
1f780 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
1f790 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
1f7a0 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 ^When [sqlite3_p
1f7b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 repare_v2()] is
1f7c0 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 used to prepare
1f7d0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 a statement, the
1f7e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 .** statement mi
1f7f0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 ght be re-prepar
1f800 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 ed during [sqlit
1f810 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 e3_step()] due t
1f820 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 o a .** schema c
1f830 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 hange. Hence, t
1f840 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
1f850 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 hould ensure tha
1f860 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 t the.** correct
1f870 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1f880 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 back remains in
1f890 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 place during the
1f8a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1f8b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 ]..**.** ^Note t
1f8c0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a hat the authoriz
1f8d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
1f8e0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 nvoked only duri
1f8f0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ng.** [sqlite3_p
1f900 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 repare()] or its
1f910 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 variants. Auth
1f920 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 orization is not
1f930 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 .** performed du
1f940 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 ring statement e
1f950 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 valuation in [sq
1f960 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 lite3_step()], u
1f970 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 nless.** as stat
1f980 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f ed in the previo
1f990 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 us paragraph, sq
1f9a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 lite3_step() inv
1f9b0 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f okes.** sqlite3_
1f9c0 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 prepare_v2() to
1f9d0 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 reprepare a stat
1f9e0 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 ement after a sc
1f9f0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a hema change..*/.
1fa00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
1fa10 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
1fa20 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
1fa30 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a izer(. sqlite3*
1fa40 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 ,. int (*xAuth)
1fa50 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
1fa60 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
1fa70 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
1fa80 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 onst char*),. v
1fa90 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 oid *pUserData.)
1faa0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1fab0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 F: Authorizer Re
1fac0 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a turn Codes.**.**
1fad0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
1fae0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
1faf0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1fb00 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 ck function] mus
1fb10 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 t.** return eith
1fb20 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f er [SQLITE_OK] o
1fb30 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 r one of these t
1fb40 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 wo constants in
1fb50 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e order.** to sign
1fb60 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 al SQLite whethe
1fb70 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 r or not the act
1fb80 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 ion is permitted
1fb90 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 . See the.** [s
1fba0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1fbb0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
1fbc0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e er documentation
1fbd0 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c ] for additional
1fbe0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e .** information.
1fbf0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
1fc00 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 SQLITE_IGNORE i
1fc10 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 s also used as a
1fc20 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c [conflict resol
1fc30 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 ution mode].** r
1fc40 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 eturned from the
1fc50 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f [sqlite3_vtab_o
1fc60 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e n_conflict()] in
1fc70 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 terface..*/.#def
1fc80 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 ine SQLITE_DENY
1fc90 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 1 /* Abort t
1fca0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
1fcb0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a with an error *
1fcc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1fcd0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 _IGNORE 2 /* D
1fce0 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 on't allow acces
1fcf0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e s, but don't gen
1fd00 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a erate an error *
1fd10 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
1fd20 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 F: Authorizer Ac
1fd30 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a tion Codes.**.**
1fd40 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
1fd50 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 t_authorizer()]
1fd60 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
1fd70 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ers a callback f
1fd80 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 unction.** that
1fd90 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 is invoked to au
1fda0 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 thorize certain
1fdb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 SQL statement ac
1fdc0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 tions. The.** s
1fdd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1fde0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
1fdf0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f is an integer co
1fe00 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 de that specifie
1fe10 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e s.** what action
1fe20 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 is being author
1fe30 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 ized. These are
1fe40 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 the integer act
1fe50 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a ion codes that.*
1fe60 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
1fe70 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 callback may be
1fe80 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 passed..**.** T
1fe90 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 hese action code
1fea0 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 values signify
1feb0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 what kind of ope
1fec0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a ration is to be.
1fed0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ** authorized.
1fee0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 The 3rd and 4th
1fef0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
1ff00 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a e authorization.
1ff10 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 ** callback func
1ff20 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 tion will be par
1ff30 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 ameters or NULL
1ff40 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 depending on whi
1ff50 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 ch of these.** c
1ff60 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 odes is used as
1ff70 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
1ff80 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 eter. ^(The 5th
1ff90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1ffa0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 e.** authorizer
1ffb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
1ffc0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
1ffd0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 base ("main", "t
1ffe0 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 emp",.** etc.) i
1fff0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 f applicable.)^
20000 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 ^The 6th parame
20010 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
20020 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a rizer callback.*
20030 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 * is the name of
20040 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 the inner-most
20050 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 trigger or view
20060 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 that is responsi
20070 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 ble for.** the a
20080 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 ccess attempt or
20090 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 NULL if this ac
200a0 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 cess attempt is
200b0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a directly from.**
200c0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 top-level SQL c
200d0 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a ode..*/./*******
200e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
200f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
20100 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a **** 3rd *******
20110 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a ***** 4th ******
20120 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 *****/.#define S
20130 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 QLITE_CREATE_IND
20140 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 EX 1
20150 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
20160 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
20170 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20180 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c LITE_CREATE_TABL
20190 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f E 2 /
201a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
201b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
201c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
201d0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
201e0 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a INDEX 3 /*
201f0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
20200 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
20210 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20220 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
20230 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 ABLE 4 /*
20240 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
20250 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
20260 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20270 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 E_CREATE_TEMP_TR
20280 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 IGGER 5 /* T
20290 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
202a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
202b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
202c0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 _CREATE_TEMP_VIE
202d0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 W 6 /* Vi
202e0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
202f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
20300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20310 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 CREATE_TRIGGER
20320 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 7 /* Tri
20330 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
20340 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
20350 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
20360 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 REATE_VIEW
20370 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 8 /* View
20380 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
20390 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
203a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
203b0 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
203c0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 9 /* Table
203d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
203e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
203f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
20400 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 P_INDEX
20410 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 10 /* Index
20420 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
20430 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
20440 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
20450 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
20460 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 11 /* Table N
20470 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
20480 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
20490 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
204a0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 TEMP_INDEX
204b0 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 12 /* Index Na
204c0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
204d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
204e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
204f0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 EMP_TABLE 1
20500 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 3 /* Table Nam
20510 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
20520 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
20530 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
20540 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 MP_TRIGGER 14
20550 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
20560 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
20570 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
20580 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
20590 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 P_VIEW 15
205a0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
205b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
205c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
205d0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 SQLITE_DROP_TRIG
205e0 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 GER 16
205f0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
20600 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
20610 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
20620 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 QLITE_DROP_VIEW
20630 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 17
20640 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
20650 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
20660 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20670 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 LITE_INSERT
20680 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 18 /
20690 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
206a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
206b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
206c0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 ITE_PRAGMA
206d0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 19 /*
206e0 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 Pragma Name
206f0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 1st arg or NULL
20700 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20710 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 TE_READ
20720 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 20 /*
20730 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
20740 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
20750 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20760 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 E_SELECT
20770 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 21 /* N
20780 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e ULL N
20790 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
207a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
207b0 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 _TRANSACTION
207c0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 22 /* Op
207d0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 eration NU
207e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
207f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20800 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 UPDATE
20810 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 23 /* Tab
20820 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c le Name Col
20830 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a umn Name */.
20840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
20850 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 TTACH
20860 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 24 /* File
20870 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c name NULL
20880 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
20890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
208a0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 TACH
208b0 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 25 /* Datab
208c0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 ase Name NULL
208d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
208e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 efine SQLITE_ALT
208f0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 ER_TABLE
20900 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 26 /* Databa
20910 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 se Name Table
20920 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
20930 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e fine SQLITE_REIN
20940 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 DEX
20950 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 27 /* Index N
20960 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
20970 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
20980 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 ine SQLITE_ANALY
20990 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ZE
209a0 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 28 /* Table Na
209b0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
209c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
209d0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
209e0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 _VTABLE 2
209f0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 9 /* Table Nam
20a00 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
20a10 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
20a20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 e SQLITE_DROP_VT
20a30 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 ABLE 30
20a40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
20a50 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d Module Nam
20a60 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
20a70 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e SQLITE_FUNCTION
20a80 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 31
20a90 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
20aa0 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 Function Na
20ab0 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 me */.#define
20ac0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 SQLITE_SAVEPOINT
20ad0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 32
20ae0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 /* Operation
20af0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 Savepoint Na
20b00 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 me */.#define S
20b10 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 QLITE_COPY
20b20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 0
20b30 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 /* No longer use
20b40 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
20b50 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 ITE_RECURSIVE
20b60 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 33 /*
20b70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
20b80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
20b90 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
20ba0 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 REF: Tracing And
20bb0 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 Profiling Funct
20bc0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ions.** METHOD:
20bd0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 sqlite3.**.** Th
20be0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 ese routines reg
20bf0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 ister callback f
20c00 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 unctions that ca
20c10 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a n be used for.**
20c20 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f tracing and pro
20c30 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 filing the execu
20c40 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 tion of SQL stat
20c50 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ements..**.** ^T
20c60 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
20c70 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
20c80 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 by sqlite3_trace
20c90 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 () is invoked at
20ca0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 .** various time
20cb0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 s when an SQL st
20cc0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 atement is being
20cd0 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 run by [sqlite3
20ce0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 _step()]..** ^Th
20cf0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 e sqlite3_trace(
20d00 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e ) callback is in
20d10 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 voked with a UTF
20d20 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 -8 rendering of
20d30 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 the.** SQL state
20d40 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 ment text as the
20d50 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 statement first
20d60 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e begins executin
20d70 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e g..** ^(Addition
20d80 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 al sqlite3_trace
20d90 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 () callbacks mig
20da0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 ht occur.** as e
20db0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 ach triggered su
20dc0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 bprogram is ente
20dd0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 red. The callba
20de0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 cks for triggers
20df0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 .** contain a UT
20e00 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 F-8 SQL comment
20e10 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 that identifies
20e20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a the trigger.)^.*
20e30 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 *.** The [SQLITE
20e40 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 _TRACE_SIZE_LIMI
20e50 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 T] compile-time
20e60 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
20e70 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 ed to limit.** t
20e80 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f he length of [bo
20e90 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 und parameter] e
20ea0 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 xpansion in the
20eb0 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 output of sqlite
20ec0 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 3_trace()..**.**
20ed0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 ^The callback f
20ee0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
20ef0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 ed by sqlite3_pr
20f00 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b ofile() is invok
20f10 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 ed.** as each SQ
20f20 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 L statement fini
20f30 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 shes. ^The prof
20f40 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e ile callback con
20f50 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 tains.** the ori
20f60 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 ginal statement
20f70 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 text and an esti
20f80 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f mate of wall-clo
20f90 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f ck time.** of ho
20fa0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 w long that stat
20fb0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 ement took to ru
20fc0 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 n. ^The profile
20fd0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d callback.** tim
20fe0 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 e is in units of
20ff0 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f nanoseconds, ho
21000 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e wever the curren
21010 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e t implementation
21020 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 .** is only capa
21030 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f ble of milliseco
21040 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f nd resolution so
21050 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 the six least s
21060 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 ignificant.** di
21070 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 gits in the time
21080 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 are meaningless
21090 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
210a0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 ns of SQLite.**
210b0 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 might provide gr
210c0 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e eater resolution
210d0 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 on the profiler
210e0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a callback. The.
210f0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 ** sqlite3_profi
21100 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 le() function is
21110 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 considered expe
21120 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a rimental and is.
21130 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 ** subject to ch
21140 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 ange in future v
21150 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
21160 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
21170 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
21180 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 DCALL sqlite3_tr
21190 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f ace(sqlite3*, vo
211a0 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 id(*xTrace)(void
211b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 *,const char*),
211c0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 void*);.SQLITE_A
211d0 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 PI SQLITE_EXPERI
211e0 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53 51 4c MENTAL void *SQL
211f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
21200 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 te3_profile(sqli
21210 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 te3*,. void(*x
21220 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 Profile)(void*,c
21230 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 onst char*,sqlit
21240 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 e3_uint64), void
21250 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
21260 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 REF: Query Progr
21270 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ess Callbacks.**
21280 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
21290 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
212a0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e te3_progress_han
212b0 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e dler(D,N,X,P) in
212c0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 terface causes t
212d0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 he callback.** f
212e0 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 unction X to be
212f0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 invoked periodic
21300 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 ally during long
21310 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 running calls t
21320 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 o.** [sqlite3_ex
21330 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ec()], [sqlite3_
21340 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c step()] and [sql
21350 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
21360 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 ] for.** databas
21370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 e connection D.
21380 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 An example use
21390 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 for this.** inte
213a0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 rface is to keep
213b0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 a GUI updated d
213c0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 uring a large qu
213d0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ery..**.** ^The
213e0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 parameter P is p
213f0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 assed through as
21400 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
21410 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 ter to the .** c
21420 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
21430 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 X. ^The parame
21440 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 ter N is the app
21450 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 roximate number
21460 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 of .** [virtual
21470 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 machine instruct
21480 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 ions] that are e
21490 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e valuated between
214a0 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 successive.** i
214b0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
214c0 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e e callback X. ^
214d0 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 If N is less tha
214e0 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 n one then the p
214f0 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c rogress.** handl
21500 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a er is disabled..
21510 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 **.** ^Only a si
21520 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 ngle progress ha
21530 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 ndler may be def
21540 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 ined at one time
21550 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 per.** [databas
21560 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 e connection]; s
21570 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f etting a new pro
21580 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 gress handler ca
21590 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 ncels the.** old
215a0 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 one. ^Setting
215b0 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e parameter X to N
215c0 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 ULL disables the
215d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
215e0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 r..** ^The progr
215f0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 ess handler is a
21600 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 lso disabled by
21610 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 setting N to a v
21620 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 alue less.** tha
21630 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 n 1..**.** ^If t
21640 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c he progress call
21650 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e back returns non
21660 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 -zero, the opera
21670 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 tion is.** inter
21680 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 rupted. This fe
21690 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 ature can be use
216a0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 d to implement a
216b0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 .** "Cancel" but
216c0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f ton on a GUI pro
216d0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 gress dialog box
216e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 ..**.** The prog
216f0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c ress handler cal
21700 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 lback must not d
21710 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
21720 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
21730 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
21740 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
21750 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 ked the progress
21760 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 handler..** Not
21770 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
21780 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
21790 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
217a0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
217b0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
217c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
217d0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
217e0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
217f0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
21800 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
21810 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c d SQLITE_STDCALL
21820 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 sqlite3_progres
21830 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 s_handler(sqlite
21840 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 3*, int, int(*)(
21850 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a void*), void*);.
21860 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
21870 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 Opening A New D
21880 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
21890 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f on.** CONSTRUCTO
218a0 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a R: sqlite3.**.**
218b0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
218c0 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 open an SQLite
218d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 database file as
218e0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
218f0 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 e .** filename a
21900 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 rgument. ^The fi
21910 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 lename argument
21920 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
21930 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 s UTF-8 for.** s
21940 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
21950 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 d sqlite3_open_v
21960 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 2() and as UTF-1
21970 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 6 in the native
21980 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f byte.** order fo
21990 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 r sqlite3_open16
219a0 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 (). ^(A [databas
219b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
219c0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a ndle is usually.
219d0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a ** returned in *
219e0 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e ppDb, even if an
219f0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 error occurs.
21a00 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 The only excepti
21a10 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 on is that.** if
21a20 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c SQLite is unabl
21a30 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 e to allocate me
21a40 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
21a50 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
21a60 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c t,.** a NULL wil
21a70 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 l be written int
21a80 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 o *ppDb instead
21a90 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 of a pointer to
21aa0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a the [sqlite3].**
21ab0 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 object.)^ ^(If
21ac0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
21ad0 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 opened (and/or c
21ae0 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 reated) successf
21af0 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 ully, then.** [S
21b00 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 QLITE_OK] is ret
21b10 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 urned. Otherwis
21b20 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 e an [error code
21b30 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e ] is returned.)^
21b40 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 ^The.** [sqlite
21b50 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 3_errmsg()] or [
21b60 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
21b70 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e ()] routines can
21b80 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 be used to obta
21b90 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 in.** an English
21ba0 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 language descri
21bb0 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 ption of the err
21bc0 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 or following a f
21bd0 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a ailure of any.**
21be0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
21bf0 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e open() routines.
21c00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 .**.** ^The defa
21c10 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c ult encoding wil
21c20 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 l be UTF-8 for d
21c30 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 atabases created
21c40 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 using.** sqlite
21c50 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 3_open() or sqli
21c60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 te3_open_v2().
21c70 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 ^The default enc
21c80 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 oding for databa
21c90 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 ses.** created u
21ca0 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 sing sqlite3_ope
21cb0 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 n16() will be UT
21cc0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
21cd0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
21ce0 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 *.** Whether or
21cf0 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 not an error occ
21d00 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f urs when it is o
21d10 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 pened, resources
21d20 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
21d30 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 ith the [databas
21d40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
21d50 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 ndle should be r
21d60 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 eleased by.** pa
21d70 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c ssing it to [sql
21d80 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 ite3_close()] wh
21d90 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 en it is no long
21da0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a er required..**.
21db0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f ** The sqlite3_o
21dc0 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 pen_v2() interfa
21dd0 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 ce works like sq
21de0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 lite3_open().**
21df0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 except that it a
21e00 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 ccepts two addit
21e10 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 ional parameters
21e20 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
21e30 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 control.** over
21e40 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 the new database
21e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 connection. ^(
21e60 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 The flags parame
21e70 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 ter to.** sqlite
21e80 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 3_open_v2() can
21e90 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 take one of.** t
21ea0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 he following thr
21eb0 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f ee values, optio
21ec0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 nally combined w
21ed0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ith the .** [SQL
21ee0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
21ef0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ], [SQLITE_OPEN_
21f00 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c FULLMUTEX], [SQL
21f10 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
21f20 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 ACHE],.** [SQLIT
21f30 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
21f40 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 CHE], and/or [SQ
21f50 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 LITE_OPEN_URI] f
21f60 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 lags:)^.**.** <d
21f70 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c l>.** ^(<dt>[SQL
21f80 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
21f90 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 Y]</dt>.** <dd>T
21fa0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
21fb0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e pened in read-on
21fc0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 ly mode. If the
21fd0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e database does n
21fe0 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 ot.** already ex
21ff0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 ist, an error is
22000 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 returned.</dd>)
22010 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 ^.**.** ^(<dt>[S
22020 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
22030 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 RITE]</dt>.** <d
22040 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
22050 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
22060 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
22070 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 if possible, or
22080 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 reading.** only
22090 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 if the file is
220a0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 write protected
220b0 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 by the operating
220c0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 system. In eit
220d0 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 her.** case the
220e0 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c database must al
220f0 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 ready exist, oth
22100 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 erwise an error
22110 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 is returned.</dd
22120 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e >)^.**.** ^(<dt>
22130 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
22140 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 DWRITE] | [SQLIT
22150 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f E_OPEN_CREATE]</
22160 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
22170 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
22180 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e d for reading an
22190 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 d writing, and i
221a0 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 s created if.**
221b0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 it does not alre
221c0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 ady exist. This
221d0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 is the behavior
221e0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 that is always u
221f0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 sed for.** sqlit
22200 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
22210 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c lite3_open16().<
22220 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a /dd>)^.** </dl>.
22230 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 **.** If the 3rd
22240 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
22250 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
22260 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 is not one of th
22270 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e e.** combination
22280 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 s shown above op
22290 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 tionally combine
222a0 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 d with other.**
222b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
222c0 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f DONLY | SQLITE_O
222d0 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 PEN_* bits].** t
222e0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
222f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
22300 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 *.** ^If the [SQ
22310 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
22320 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 X] flag is set,
22330 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
22340 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
22350 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c opens in the mul
22360 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 ti-thread [threa
22370 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f ding mode] as lo
22380 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 ng as the single
22390 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 -thread.** mode
223a0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 has not been set
223b0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 at compile-time
223c0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 or start-time.
223d0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c ^If the.** [SQL
223e0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
223f0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 EX] flag is set
22400 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
22410 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 e connection ope
22420 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 ns.** in the ser
22430 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
22440 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 ng mode] unless
22450 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 single-thread wa
22460 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 s.** previously
22470 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 selected at comp
22480 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 ile-time or star
22490 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 t-time..** ^The
224a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 [SQLITE_OPEN_SHA
224b0 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 REDCACHE] flag c
224c0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 auses the databa
224d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f se connection to
224e0 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 be.** eligible
224f0 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 to use [shared c
22500 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 ache mode], rega
22510 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
22520 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a r or not shared.
22530 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 ** cache is enab
22540 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 led using [sqlit
22550 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 e3_enable_shared
22560 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 _cache()]. ^The
22570 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
22580 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 _PRIVATECACHE] f
22590 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 lag causes the d
225a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
225b0 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 on to not.** par
225c0 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 ticipate in [sha
225d0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 red cache mode]
225e0 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e even if it is en
225f0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 abled..**.** ^Th
22600 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
22610 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
22620 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e en_v2() is the n
22630 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ame of the.** [s
22640 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
22650 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
22660 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
22670 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 stem interface t
22680 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 hat.** the new d
22690 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
226a0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 on should use.
226b0 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 ^If the fourth p
226c0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 arameter is.** a
226d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
226e0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b en the default [
226f0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
22700 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a ect is used..**.
22710 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e ** ^If the filen
22720 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a ame is ":memory:
22730 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 ", then a privat
22740 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d e, temporary in-
22750 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a memory database.
22760 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f ** is created fo
22770 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e r the connection
22780 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f . ^This in-memo
22790 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c ry database will
227a0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 vanish when.**
227b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
227c0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
227d0 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 d. Future versi
227e0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 ons of SQLite mi
227f0 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 ght.** make use
22800 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 of additional sp
22810 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 ecial filenames
22820 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 that begin with
22830 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 the ":" characte
22840 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f r..** It is reco
22850 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 mmended that whe
22860 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c n a database fil
22870 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 ename actually d
22880 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a oes begin with.*
22890 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 * a ":" characte
228a0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 r you should pre
228b0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 fix the filename
228c0 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 with a pathname
228d0 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 such as.** "./"
228e0 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 to avoid ambigu
228f0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ity..**.** ^If t
22900 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 he filename is a
22910 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 n empty string,
22920 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 then a private,
22930 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d temporary.** on-
22940 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 disk database wi
22950 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 ll be created.
22960 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 ^This private da
22970 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a tabase will be.*
22980 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
22990 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 deleted as soon
229a0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 as the database
229b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
229c0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 osed..**.** [[UR
229d0 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 I filenames in s
229e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 qlite3_open()]]
229f0 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 <h3>URI Filename
22a00 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 s</h3>.**.** ^If
22a10 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 [URI filename]
22a20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 interpretation i
22a30 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 s enabled, and t
22a40 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
22a50 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 ment.** begins w
22a60 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 ith "file:", the
22a70 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 n the filename i
22a80 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
22a90 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 a URI. ^URI.**
22aa0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 filename interpr
22ab0 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c etation is enabl
22ac0 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 ed if the [SQLIT
22ad0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 E_OPEN_URI] flag
22ae0 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 is.** set in th
22af0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
22b00 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 t to sqlite3_ope
22b10 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 n_v2(), or if it
22b20 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 has.** been ena
22b30 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 bled globally us
22b40 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
22b50 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 CONFIG_URI] opti
22b60 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b on with the.** [
22b70 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
22b80 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 ] method or by t
22b90 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 he [SQLITE_USE_U
22ba0 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 RI] compile-time
22bb0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f option..** As o
22bc0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e f SQLite version
22bd0 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 3.7.7, URI file
22be0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 name interpretat
22bf0 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 ion is turned of
22c00 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c f.** by default,
22c10 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 but future rele
22c20 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d ases of SQLite m
22c30 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 ight enable URI
22c40 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 filename.** inte
22c50 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 rpretation by de
22c60 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 fault. See "[UR
22c70 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f I filenames]" fo
22c80 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
22c90 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
22ca0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 ** URI filenames
22cb0 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f are parsed acco
22cc0 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 rding to RFC 398
22cd0 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6. ^If the URI c
22ce0 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 ontains an.** au
22cf0 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 thority, then it
22d00 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
22d10 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 an empty string
22d20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a or the string .*
22d30 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e * "localhost". ^
22d40 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 If the authority
22d50 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 is not an empty
22d60 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 string or "loca
22d70 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 lhost", an .** e
22d80 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
22d90 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 to the caller.
22da0 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f ^The fragment co
22db0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 mponent of a URI
22dc0 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 , if .** present
22dd0 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a , is ignored..**
22de0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 .** ^SQLite uses
22df0 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e the path compon
22e00 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 ent of the URI a
22e10 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
22e20 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 e disk file.** w
22e30 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 hich contains th
22e40 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 e database. ^If
22e50 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 the path begins
22e60 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 with a '/' chara
22e70 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 cter, .** then i
22e80 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 t is interpreted
22e90 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 as an absolute
22ea0 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 path. ^If the pa
22eb0 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 th does not begi
22ec0 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 n .** with a '/'
22ed0 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 (meaning that t
22ee0 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 he authority sec
22ef0 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 tion is omitted
22f00 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a from the URI).**
22f10 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 then the path i
22f20 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
22f30 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 a relative path
22f40 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f . .** ^(On windo
22f50 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f ws, the first co
22f60 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 mponent of an ab
22f70 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 solute path .**
22f80 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 is a drive speci
22f90 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 fication (e.g. "
22fa0 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b C:").)^.**.** [[
22fb0 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 core URI query p
22fc0 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 arameters]].** T
22fd0 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 he query compone
22fe0 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 nt of a URI may
22ff0 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 contain paramete
23000 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 rs that are inte
23010 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 rpreted.** eithe
23020 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 r by SQLite itse
23030 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 lf, or by a [VFS
23040 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d | custom VFS im
23050 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a plementation]..*
23060 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 * SQLite and its
23070 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 built-in [VFSes
23080 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a ] interpret the.
23090 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 ** following que
230a0 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a ry parameters:.*
230b0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c *.** <ul>.** <
230c0 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 li> <b>vfs</b>:
230d0 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d ^The "vfs" param
230e0 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 eter may be used
230f0 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 to specify the
23100 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 name of.** a
23110 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 VFS object that
23120 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 provides the op
23130 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 erating system i
23140 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 nterface that sh
23150 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 ould.** be u
23160 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 sed to access th
23170 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
23180 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 on disk. ^If thi
23190 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 s option is set
231a0 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 to.** an emp
231b0 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 ty string the de
231c0 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 fault VFS object
231d0 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 is used. ^Speci
231e0 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e fying an unknown
231f0 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 .** VFS is a
23200 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c n error. ^If sql
23210 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
23220 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 s used and the v
23230 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 fs option is.**
23240 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 present, the
23250 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 n the VFS specif
23260 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f ied by the optio
23270 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e n takes preceden
23280 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 ce over.** t
23290 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 he value passed
232a0 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 as the fourth pa
232b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
232c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a e3_open_v2()..**
232d0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f .** <li> <b>mo
232e0 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f de</b>: ^(The mo
232f0 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 de parameter may
23300 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 be set to eithe
23310 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a r "ro", "rw",.**
23320 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 "rwc", or "
23330 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 memory". Attempt
23340 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f ing to set it to
23350 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 any other value
23360 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 is.** an er
23370 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e ror)^. .** ^
23380 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 If "ro" is speci
23390 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 fied, then the d
233a0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
233b0 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 d for read-only
233c0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 .** access,
233d0 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b just as if the [
233e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
233f0 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 ONLY] flag had b
23400 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a een set in the .
23410 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 ** third arg
23420 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
23430 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 _open_v2(). ^If
23440 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 the mode option
23450 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 is set to .**
23460 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 "rw", then the
23470 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
23480 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 ned for read-wri
23490 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 te (but not crea
234a0 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 te) .** acce
234b0 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 ss, as if SQLITE
234c0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 _OPEN_READWRITE
234d0 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f (but not SQLITE_
234e0 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 OPEN_CREATE) had
234f0 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 .** been se
23500 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 t. ^Value "rwc"
23510 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f is equivalent to
23520 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a setting both .*
23530 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 * SQLITE_OPE
23540 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 N_READWRITE and
23550 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
23560 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 TE. ^If the mod
23570 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 e option is.**
23580 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 set to "memor
23590 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b y" then a pure [
235a0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
235b0 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 se] that never r
235c0 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 eads.** or w
235d0 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 rites from disk
235e0 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 is used. ^It is
235f0 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 an error to spec
23600 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a ify a value for.
23610 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 ** the mode
23620 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 parameter that i
23630 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 s less restricti
23640 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 ve than that spe
23650 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 cified by.**
23660 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 the flags passe
23670 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 d in the third p
23680 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
23690 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a te3_open_v2()..*
236a0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 *.** <li> <b>c
236b0 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 ache</b>: ^The c
236c0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d ache parameter m
236d0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 ay be set to eit
236e0 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a her "shared" or.
236f0 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 ** "private"
23700 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f . ^Setting it to
23710 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 "shared" is equ
23720 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 ivalent to setti
23730 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 ng the.** SQ
23740 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
23750 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 CACHE bit in the
23760 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
23770 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 passed to.**
23780 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
23790 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 (). ^Setting the
237a0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 cache parameter
237b0 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 to "private" is
237c0 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c .** equival
237d0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 ent to setting t
237e0 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 he SQLITE_OPEN_P
237f0 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e RIVATECACHE bit.
23800 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 .** ^If sqli
23810 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
23820 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 used and the "c
23830 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 ache" parameter
23840 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a is present in.**
23850 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e a URI filen
23860 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f ame, its value o
23870 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 verrides any beh
23880 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 avior requested
23890 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 by setting.**
238a0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 SQLITE_OPEN_PR
238b0 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 IVATECACHE or SQ
238c0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
238d0 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a CACHE flag..**.*
238e0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c * <li> <b>psow<
238f0 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 /b>: ^The psow p
23900 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 arameter indicat
23910 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f es whether or no
23920 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f t the.** [po
23930 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 wersafe overwrit
23940 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 e] property does
23950 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 or does not app
23960 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 ly to the.**
23970 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f storage media o
23980 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 n which the data
23990 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 base file reside
239a0 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c s..**.** <li> <
239b0 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 b>nolock</b>: ^T
239c0 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 he nolock parame
239d0 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e ter is a boolean
239e0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
239f0 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 .** which if
23a00 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 set disables fi
23a10 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f le locking in ro
23a20 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d llback journal m
23a30 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 odes. This.**
23a40 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 is useful for
23a50 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 accessing a dat
23a60 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 abase on a files
23a70 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 ystem that does
23a80 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f not.** suppo
23a90 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 rt locking. Cau
23aa0 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 tion: Database
23ab0 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 corruption might
23ac0 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a result if two.*
23ad0 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 * or more pr
23ae0 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f ocesses write to
23af0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
23b00 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f se and any one o
23b10 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 f those.** p
23b20 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f rocesses uses no
23b30 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c lock=1..**.** <
23b40 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 li> <b>immutable
23b50 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 </b>: ^The immut
23b60 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 able parameter i
23b70 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 s a boolean quer
23b80 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 y.** paramet
23b90 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 er that indicate
23ba0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 s that the datab
23bb0 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 ase file is stor
23bc0 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 ed on.** rea
23bd0 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e d-only media. ^
23be0 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 When immutable i
23bf0 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 s set, SQLite as
23c00 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a sumes that the.*
23c10 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 * database f
23c20 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 ile cannot be ch
23c30 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 anged, even by a
23c40 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 process with hi
23c50 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 gher.** priv
23c60 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 ilege, and so th
23c70 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
23c80 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 ened read-only a
23c90 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a nd all locking.*
23ca0 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 * and change
23cb0 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 detection is di
23cc0 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e sabled. Caution
23cd0 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d : Setting the im
23ce0 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 mutable.** p
23cf0 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 roperty on a dat
23d00 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 abase file that
23d10 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 does in fact cha
23d20 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a nge can result.*
23d30 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 * in incorre
23d40 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 ct query results
23d50 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f and/or [SQLITE_
23d60 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e CORRUPT] errors.
23d70 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f .** See also
23d80 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f : [SQLITE_IOCAP_
23d90 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 IMMUTABLE]..**
23da0 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a .** </ul>.*
23db0 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 *.** ^Specifying
23dc0 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 an unknown para
23dd0 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 meter in the que
23de0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 ry component of
23df0 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a a URI is not an.
23e00 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 ** error. Futur
23e10 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
23e20 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 Lite might under
23e30 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c stand additional
23e40 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 query.** parame
23e50 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 ters. See "[que
23e60 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 ry parameters wi
23e70 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 th special meani
23e80 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 ng to SQLite]" f
23e90 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c or.** additional
23ea0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
23eb0 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 .** [[URI filena
23ec0 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 me examples]] <h
23ed0 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 3>URI filename e
23ee0 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a xamples</h3>.**.
23ef0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 ** <table border
23f00 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 ="1" align=cente
23f10 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e r cellpadding=5>
23f20 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 .** <tr><th> URI
23f30 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 filenames <th>
23f40 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c Results.** <tr><
23f50 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 td> file:data.db
23f60 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
23f70 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 Open the file
23f80 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 "data.db" in th
23f90 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 e current direct
23fa0 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ory..** <tr><td>
23fb0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 file:/home/fred
23fc0 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 /data.db<br>.**
23fd0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f file://
23fe0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
23ff0 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 db <br> .**
24000 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 file://loca
24010 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f lhost/home/fred/
24020 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 data.db <br> <td
24030 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f > .** O
24040 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
24050 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 file "/home/fre
24060 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c d/data.db"..** <
24070 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 tr><td> file://d
24080 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 arkstar/home/fre
24090 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a d/data.db <td> .
240a0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 ** An e
240b0 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 rror. "darkstar"
240c0 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e is not a recogn
240d0 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a ized authority..
240e0 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 ** <tr><td style
240f0 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f ="white-space:no
24100 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 wrap"> .**
24110 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 file:///C:/D
24120 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 ocuments%20and%2
24130 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 0Settings/fred/D
24140 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a esktop/data.db.*
24150 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f * <td> Windo
24160 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 ws only: Open th
24170 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 e file "data.db"
24180 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 on fred's deskt
24190 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 op on drive.**
241a0 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 C:. Note
241b0 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 that the %20 es
241c0 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 caping in this e
241d0 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 xample is not st
241e0 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 rictly .**
241f0 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 necessary -
24200 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 space characters
24210 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 can be used lit
24220 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 erally.**
24230 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 in URI filena
24240 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e mes..** <tr><td>
24250 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f file:data.db?mo
24260 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 de=ro&cache=priv
24270 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 ate <td> .**
24280 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 Open file
24290 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 "data.db" in the
242a0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f current directo
242b0 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 ry for read-only
242c0 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 access..**
242d0 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 Regardless
242e0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
242f0 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d t shared-cache m
24300 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 ode is enabled b
24310 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 y.** de
24320 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 fault, use a pri
24330 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c vate cache..** <
24340 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f tr><td> file:/ho
24350 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f me/fred/data.db?
24360 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 vfs=unix-dotfile
24370 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <td>.**
24380 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f Open file "/ho
24390 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 me/fred/data.db"
243a0 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 . Use the specia
243b0 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 l VFS "unix-dotf
243c0 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 ile".**
243d0 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 that uses dot-f
243e0 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 iles in place of
243f0 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 posix advisory
24400 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e locking..** <tr>
24410 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 <td> file:data.d
24420 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 b?mode=readonly
24430 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <td> .**
24440 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 An error. "rea
24450 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 donly" is not a
24460 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 valid option for
24470 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 the "mode" para
24480 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c meter..** </tabl
24490 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 e>.**.** ^URI he
244a0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 xadecimal escape
244b0 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 sequences (%HH)
244c0 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 are supported w
244d0 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 ithin the path a
244e0 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 nd.** query comp
244f0 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e onents of a URI.
24500 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 A hexadecimal e
24510 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 scape sequence c
24520 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 onsists of a.**
24530 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 percent sign - "
24540 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 %" - followed by
24550 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 exactly two hex
24560 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 adecimal digits
24570 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 .** specifying a
24580 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e n octet value. ^
24590 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 Before the path
245a0 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 or query compone
245b0 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 nts of a.** URI
245c0 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 filename are int
245d0 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 erpreted, they a
245e0 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 re encoded using
245f0 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a UTF-8 and all .
24600 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 ** hexadecimal e
24610 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 scape sequences
24620 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 replaced by a si
24630 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 ngle byte contai
24640 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 ning the.** corr
24650 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e esponding octet.
24660 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 If this process
24670 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e generates an in
24680 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f valid UTF-8 enco
24690 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 ding,.** the res
246a0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
246b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 ed..**.** <b>Not
246c0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 e to Windows use
246d0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 rs:</b> The enc
246e0 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 oding used for t
246f0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
24700 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 ment.** of sqlit
24710 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
24720 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
24730 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e must be UTF-8, n
24740 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 ot whatever.** c
24750 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 odepage is curre
24760 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 ntly defined. F
24770 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e ilenames contain
24780 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 ing internationa
24790 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 l.** characters
247a0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
247b0 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 d to UTF-8 prior
247c0 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d to passing them
247d0 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 into.** sqlite3
247e0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
247f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a e3_open_v2()..**
24800 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 .** <b>Note to W
24810 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 indows Runtime u
24820 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 sers:</b> The t
24830 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f emporary directo
24840 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a ry must be set.*
24850 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 * prior to calli
24860 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ng sqlite3_open(
24870 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 ) or sqlite3_ope
24880 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 n_v2(). Otherwi
24890 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 se, various.** f
248a0 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 eatures that req
248b0 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 uire the use of
248c0 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 temporary files
248d0 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 may fail..**.**
248e0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
248f0 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 e3_temp_director
24900 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 y].*/.SQLITE_API
24910 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
24920 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ALL sqlite3_open
24930 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a (. const char *
24940 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 filename, /* D
24950 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
24960 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 (UTF-8) */. sq
24970 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 lite3 **ppDb
24980 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
24990 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
249a0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 /.);.SQLITE_API
249b0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
249c0 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 LL sqlite3_open1
249d0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 6(. const void
249e0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
249f0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
24a00 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 e (UTF-16) */.
24a10 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
24a20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
24a30 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
24a40 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
24a50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
24a60 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 CALL sqlite3_ope
24a70 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 n_v2(. const ch
24a80 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 ar *filename,
24a90 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
24aa0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a name (UTF-8) */.
24ab0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
24ac0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 , /* OUT
24ad0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
24ae0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 le */. int flag
24af0 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 s,
24b00 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f /* Flags */. co
24b10 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 nst char *zVfs
24b20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 /* Name of
24b30 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 VFS module to u
24b40 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 se */.);../*.**
24b50 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e CAPI3REF: Obtain
24b60 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 Values For URI
24b70 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a Parameters.**.**
24b80 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 These are utili
24b90 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 ty routines, use
24ba0 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 ful to VFS imple
24bb0 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 mentations, that
24bc0 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 check.** to see
24bd0 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 if a database f
24be0 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 ile was a URI th
24bf0 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 at contained a s
24c00 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a pecific query .*
24c10 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 * parameter, and
24c20 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 if so obtains t
24c30 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 he value of that
24c40 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
24c50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 ..**.** If F is
24c60 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
24c70 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 ename pointer pa
24c80 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f ssed into the xO
24c90 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 pen() method of
24ca0 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d .** a VFS implem
24cb0 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 entation when th
24cc0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
24cd0 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 r to xOpen() has
24ce0 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 one or .** more
24cf0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f of the [SQLITE_
24d00 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 OPEN_URI] or [SQ
24d10 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 LITE_OPEN_MAIN_D
24d20 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a B] bits set and.
24d30 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 ** P is the name
24d40 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 of the query pa
24d50 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a rameter, then.**
24d60 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 sqlite3_uri_par
24d70 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 ameter(F,P) retu
24d80 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 rns the value of
24d90 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 the P.** parame
24da0 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 ter if it exists
24db0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 or a NULL point
24dc0 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 er if P does not
24dd0 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a appear as a .**
24de0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
24df0 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 on F. If P is
24e00 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 a query paramete
24e10 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f r of F.** has no
24e20 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c explicit value,
24e30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
24e40 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 i_parameter(F,P)
24e50 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f returns.** a po
24e60 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 inter to an empt
24e70 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 y string..**.**
24e80 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f The sqlite3_uri_
24e90 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 boolean(F,P,B) r
24ea0 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 outine assumes t
24eb0 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 hat P is a boole
24ec0 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 an.** parameter
24ed0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 and returns true
24ee0 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 (1) or false (0
24ef0 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 ) according to t
24f00 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 he value.** of P
24f10 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 . The sqlite3_u
24f20 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
24f30 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
24f40 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 s true (1) if th
24f50 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 e.** value of qu
24f60 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 ery parameter P
24f70 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c is one of "yes",
24f80 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 "true", or "on"
24f90 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 in any.** case
24fa0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 or if the value
24fb0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f begins with a no
24fc0 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 n-zero number.
24fd0 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f The .** sqlite3_
24fe0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
24ff0 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 B) routines retu
25000 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 rns false (0) if
25010 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a the value of.**
25020 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
25030 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f P is one of "no
25040 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 ", "false", or "
25050 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 off" in any case
25060 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 or.** if the va
25070 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 lue begins with
25080 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 a numeric zero.
25090 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 If P is not a q
250a0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 uery.** paramete
250b0 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 r on F or if the
250c0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 value of P is d
250d0 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e oes not match an
250e0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 y of the.** abov
250f0 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f e, then sqlite3_
25100 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
25110 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 B) returns (B!=0
25120 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )..**.** The sql
25130 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 ite3_uri_int64(F
25140 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f ,P,D) routine co
25150 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 nverts the value
25160 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 of P into a.**
25170 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
25180 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e teger and return
25190 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 s that integer,
251a0 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e or D if P does n
251b0 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 ot.** exist. If
251c0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
251d0 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 is something oth
251e0 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 er than an integ
251f0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f er, then.** zero
25200 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
25210 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e .** If F is a N
25220 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
25230 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 n sqlite3_uri_pa
25240 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 rameter(F,P) ret
25250 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a urns NULL and.**
25260 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
25270 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 lean(F,P,B) retu
25280 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 rns B. If F is
25290 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 not a NULL point
252a0 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 er and.** is not
252b0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
252c0 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 pathname pointe
252d0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 r that SQLite pa
252e0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f ssed into the xO
252f0 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f pen.** VFS metho
25300 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 d, then the beha
25310 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 vior of this rou
25320 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 tine is undefine
25330 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a d and probably.*
25340 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a * undesirable..*
25350 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
25360 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f st char *SQLITE_
25370 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
25380 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f uri_parameter(co
25390 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e nst char *zFilen
253a0 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 ame, const char
253b0 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 *zParam);.SQLITE
253c0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
253d0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
253e0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 uri_boolean(cons
253f0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 t char *zFile, c
25400 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 onst char *zPara
25410 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 m, int bDefault)
25420 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c ;.SQLITE_API sql
25430 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 ite3_int64 SQLIT
25440 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
25450 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 3_uri_int64(cons
25460 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 t char*, const c
25470 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e har*, sqlite3_in
25480 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 t64);.../*.** CA
25490 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f PI3REF: Error Co
254a0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 des And Messages
254b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
254c0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 te3.**.** ^If th
254d0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 e most recent sq
254e0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c lite3_* API call
254f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
25500 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 .** [database c
25510 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 onnection] D fai
25520 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 led, then the sq
25530 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 lite3_errcode(D)
25540 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 interface.** re
25550 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 turns the numeri
25560 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 c [result code]
25570 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 or [extended res
25580 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 ult code] for th
25590 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a at.** API call..
255a0 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 ** If the most r
255b0 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 ecent API call w
255c0 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a as successful,.*
255d0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 * then the retur
255e0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c n value from sql
255f0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 ite3_errcode() i
25600 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 s undefined..**
25610 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 ^The sqlite3_ext
25620 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a ended_errcode().
25630 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
25640 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 the same except
25650 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 that it always r
25660 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b eturns the .** [
25670 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
25680 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 code] even when
25690 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
256a0 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 codes are.** dis
256b0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 abled..**.** ^Th
256c0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 e sqlite3_errmsg
256d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 () and sqlite3_e
256e0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e rrmsg16() return
256f0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 English-languag
25700 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 e.** text that d
25710 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 escribes the err
25720 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 or, as either UT
25730 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 F-8 or UTF-16 re
25740 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e spectively..** ^
25750 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 (Memory to hold
25760 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
25770 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 e string is mana
25780 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a ged internally..
25790 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
257a0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 on does not need
257b0 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 to worry about
257c0 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 freeing the resu
257d0 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 lt..** However,
257e0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 the error string
257f0 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 might be overwr
25800 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 itten or dealloc
25810 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 ated by.** subse
25820 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f quent calls to o
25830 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
25840 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e rface functions.
25850 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 )^.**.** ^The sq
25860 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 lite3_errstr() i
25870 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
25880 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e the English-lan
25890 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 guage text.** th
258a0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 at describes the
258b0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 [result code],
258c0 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d as UTF-8..** ^(M
258d0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
258e0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
258f0 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 string is manage
25900 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 d internally.**
25910 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 and must not be
25920 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 freed by the app
25930 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a lication)^..**.*
25940 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 * When the seria
25950 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
25960 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 mode] is in use
25970 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 , it might be th
25980 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 e.** case that a
25990 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 second error oc
259a0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 curs on a separa
259b0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 te thread in bet
259c0 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 ween.** the time
259d0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 of the first er
259e0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c ror and the call
259f0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 to these interf
25a00 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 aces..** When th
25a10 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 at happens, the
25a20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c second error wil
25a30 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 l be reported si
25a40 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 nce these.** int
25a50 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 erfaces always r
25a60 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 eport the most r
25a70 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 ecent result. T
25a80 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c o avoid.** this,
25a90 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e each thread can
25aa0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 obtain exclusiv
25ab0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 e use of the [da
25ac0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
25ad0 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b n] D.** by invok
25ae0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
25af0 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 ex_enter]([sqlit
25b00 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 e3_db_mutex](D))
25b10 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e before beginnin
25b20 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e g.** to use D an
25b30 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 d invoking [sqli
25b40 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d te3_mutex_leave]
25b50 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 ([sqlite3_db_mut
25b60 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a ex](D)) after.**
25b70 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 all calls to th
25b80 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 e interfaces lis
25b90 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d ted here are com
25ba0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 pleted..**.** If
25bb0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 an interface fa
25bc0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f ils with SQLITE_
25bd0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 MISUSE, that mea
25be0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 ns the interface
25bf0 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 .** was invoked
25c00 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 incorrectly by t
25c10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 he application.
25c20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 In that case, t
25c30 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 he.** error code
25c40 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 and message may
25c50 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 or may not be s
25c60 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 et..*/.SQLITE_AP
25c70 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
25c80 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 CALL sqlite3_err
25c90 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 code(sqlite3 *db
25ca0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
25cb0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
25cc0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
25cd0 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 d_errcode(sqlite
25ce0 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 3 *db);.SQLITE_A
25cf0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 PI const char *S
25d00 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
25d10 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c lite3_errmsg(sql
25d20 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 ite3*);.SQLITE_A
25d30 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 PI const void *S
25d40 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
25d50 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 lite3_errmsg16(s
25d60 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 qlite3*);.SQLITE
25d70 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
25d80 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
25d90 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 sqlite3_errstr(i
25da0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
25db0 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 3REF: Prepared S
25dc0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a tatement Object.
25dd0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 ** KEYWORDS: {pr
25de0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
25df0 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 } {prepared stat
25e00 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e ements}.**.** An
25e10 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
25e20 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 s object represe
25e30 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c nts a single SQL
25e40 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a statement that.
25e50 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 ** has been comp
25e60 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 iled into binary
25e70 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 form and is rea
25e80 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 dy to be evaluat
25e90 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 ed..**.** Think
25ea0 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 of each SQL stat
25eb0 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 ement as a separ
25ec0 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f ate computer pro
25ed0 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 gram. The.** or
25ee0 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 iginal SQL text
25ef0 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 is source code.
25f00 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 A prepared stat
25f10 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a ement object .**
25f20 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 is the compiled
25f30 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 object code. A
25f40 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 ll SQL must be c
25f50 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a onverted into a.
25f60 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ** prepared stat
25f70 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 ement before it
25f80 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a can be run..**.*
25f90 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 * The life-cycle
25fa0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 of a prepared s
25fb0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
25fc0 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b usually goes lik
25fd0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f e this:.**.** <o
25fe0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 l>.** <li> Creat
25ff0 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 e the prepared s
26000 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
26010 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 using [sqlite3_p
26020 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a repare_v2()]..**
26030 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 <li> Bind value
26040 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 s to [parameters
26050 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 ] using the sqli
26060 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 te3_bind_*().**
26070 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e interfaces.
26080 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 .** <li> Run the
26090 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 SQL by calling
260a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
260b0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
260c0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 es..** <li> Rese
260d0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 t the prepared s
260e0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
260f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
26100 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a then go back.**
26110 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e to step 2.
26120 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f Do this zero o
26130 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a r more times..**
26140 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 <li> Destroy th
26150 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b e object using [
26160 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
26170 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f ()]..** </ol>.*/
26180 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
26190 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c sqlite3_stmt sql
261a0 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a ite3_stmt;../*.*
261b0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
261c0 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d time Limits.** M
261d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
261e0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 *.** ^(This inte
261f0 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 rface allows the
26200 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 size of various
26210 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 constructs to b
26220 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 e limited.** on
26230 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 a connection by
26240 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 connection basis
26250 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 . The first par
26260 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
26270 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
26280 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d ction] whose lim
26290 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 it is to be set
262a0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 or queried. The
262b0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
262c0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 eter is one of t
262d0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f he [limit catego
262e0 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e ries] that defin
262f0 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 e a.** class of
26300 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 constructs to be
26310 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 size limited.
26320 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
26330 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 ter is the.** ne
26340 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 w limit for that
26350 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a construct.)^.**
26360 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 .** ^If the new
26370 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 limit is a negat
26380 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 ive number, the
26390 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 limit is unchang
263a0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 ed..** ^(For eac
263b0 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 h limit category
263c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 SQLITE_LIMIT_<i
263d0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 >NAME</i> there
263e0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 is a .** [limits
263f0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f | hard upper bo
26400 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 und].** set at c
26410 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 ompile-time by a
26420 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
26430 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 macro called.**
26440 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 [limits | SQLITE
26450 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e _MAX_<i>NAME</i>
26460 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d ]..** (The "_LIM
26470 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 IT_" in the name
26480 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 is changed to "
26490 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 _MAX_".))^.** ^A
264a0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 ttempts to incre
264b0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 ase a limit abov
264c0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 e its hard upper
264d0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 bound are.** si
264e0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 lently truncated
264f0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 to the hard upp
26500 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 er bound..**.**
26510 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 ^Regardless of w
26520 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
26530 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e e limit was chan
26540 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 ged, the .** [sq
26550 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 lite3_limit()] i
26560 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
26570 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 the prior value
26580 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a of the limit..*
26590 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e * ^Hence, to fin
265a0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 d the current va
265b0 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 lue of a limit w
265c0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 ithout changing
265d0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e it,.** simply in
265e0 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 voke this interf
265f0 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 ace with the thi
26600 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 rd parameter set
26610 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 to -1..**.** Ru
26620 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 n-time limits ar
26630 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 e intended for u
26640 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f se in applicatio
26650 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a ns that manage.*
26660 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e * both their own
26670 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 internal databa
26680 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 se and also data
26690 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 bases that are c
266a0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 ontrolled.** by
266b0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e untrusted extern
266c0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 al sources. An
266d0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 example applicat
266e0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a ion might be a.*
266f0 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 * web browser th
26700 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 at has its own d
26710 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f atabases for sto
26720 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 ring history and
26730 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 .** separate dat
26740 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 abases controlle
26750 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 d by JavaScript
26760 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 applications dow
26770 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 nloaded.** off t
26780 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 he Internet. Th
26790 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 e internal datab
267a0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 ases can be give
267b0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 n the.** large,
267c0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 default limits.
267d0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 Databases manag
267e0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 ed by external s
267f0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 ources can.** be
26800 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c given much smal
26810 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 ler limits desig
26820 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 ned to prevent a
26830 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 denial of servi
26840 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 ce.** attack. D
26850 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 evelopers might
26860 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 also want to use
26870 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 the [sqlite3_se
26880 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a t_authorizer()].
26890 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 ** interface to
268a0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 further control
268b0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 untrusted SQL.
268c0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 The size of the
268d0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 database.** crea
268e0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 ted by an untrus
268f0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 ted script can b
26900 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e e contained usin
26910 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 g the.** [max_pa
26920 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d ge_count] [PRAGM
26930 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 A]..**.** New ru
26940 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 n-time limit cat
26950 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 egories may be a
26960 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
26970 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 eleases..*/.SQLI
26980 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
26990 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
269a0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 3_limit(sqlite3*
269b0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 , int id, int ne
269c0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 wVal);../*.** CA
269d0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
269e0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 Limit Categorie
269f0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
26a00 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 limit category}
26a10 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 {*limit categori
26a20 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 es}.**.** These
26a30 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
26a40 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d various perform
26a50 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 ance limits.** t
26a60 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 hat can be lower
26a70 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 ed at run-time u
26a80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 sing [sqlite3_li
26a90 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 mit()]..** The s
26aa0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d ynopsis of the m
26ab0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 eanings of the v
26ac0 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 arious limits is
26ad0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a shown below..**
26ae0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f Additional info
26af0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c rmation is avail
26b00 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 able at [limits
26b10 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 | Limits in SQLi
26b20 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a te]..**.** <dl>.
26b30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
26b40 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 T_LENGTH]] ^(<dt
26b50 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 >SQLITE_LIMIT_LE
26b60 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
26b70 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a >The maximum siz
26b80 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 e of any string
26b90 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 or BLOB or table
26ba0 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c row, in bytes.<
26bb0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
26bc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
26bd0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 ENGTH]] ^(<dt>SQ
26be0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
26bf0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
26c00 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
26c10 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 ngth of an SQL s
26c20 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 tatement, in byt
26c30 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a es.</dd>)^.**.**
26c40 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
26c50 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 COLUMN]] ^(<dt>S
26c60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
26c70 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 MN</dt>.** <dd>T
26c80 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
26c90 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
26ca0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 a table definiti
26cb0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 on or in the.**
26cc0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 result set of a
26cd0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 [SELECT] or the
26ce0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
26cf0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 f columns in an
26d00 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 index.** or in a
26d10 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 n ORDER BY or GR
26d20 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f OUP BY clause.</
26d30 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
26d40 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
26d50 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 DEPTH]] ^(<dt>SQ
26d60 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
26d70 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 DEPTH</dt>.** <d
26d80 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 d>The maximum de
26d90 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 pth of the parse
26da0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 tree on any exp
26db0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a ression.</dd>)^.
26dc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
26dd0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
26de0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c LECT]] ^(<dt>SQL
26df0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
26e00 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a ND_SELECT</dt>.*
26e10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
26e20 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d m number of term
26e30 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 s in a compound
26e40 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
26e50 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
26e60 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 [SQLITE_LIMIT_VD
26e70 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 BE_OP]] ^(<dt>SQ
26e80 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
26e90 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 OP</dt>.** <dd>T
26ea0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
26eb0 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e r of instruction
26ec0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d s in a virtual m
26ed0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a achine program.*
26ee0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d * used to implem
26ef0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 ent an SQL state
26f00 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 ment. This limi
26f10 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 t is not current
26f20 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 ly.** enforced,
26f30 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 though that migh
26f40 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f t be added in so
26f50 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 me future releas
26f60 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c e of.** SQLite.<
26f70 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
26f80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
26f90 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 TION_ARG]] ^(<dt
26fa0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 >SQLITE_LIMIT_FU
26fb0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a NCTION_ARG</dt>.
26fc0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
26fd0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 um number of arg
26fe0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 uments on a func
26ff0 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a tion.</dd>)^.**.
27000 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
27010 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c T_ATTACHED]] ^(<
27020 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
27030 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a ATTACHED</dt>.**
27040 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
27050 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 number of [ATTA
27060 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 CH | attached da
27070 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e tabases].)^</dd>
27080 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
27090 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
270a0 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e RN_LENGTH]].** ^
270b0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
270c0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
270d0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
270e0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
270f0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 ngth of the patt
27100 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ern argument to
27110 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a the [LIKE] or.**
27120 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 [GLOB] operator
27130 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 s.</dd>)^.**.**
27140 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 [[SQLITE_LIMIT_V
27150 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d ARIABLE_NUMBER]]
27160 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 .** ^(<dt>SQLITE
27170 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
27180 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c NUMBER</dt>.** <
27190 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 dd>The maximum i
271a0 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 ndex number of a
271b0 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 ny [parameter] i
271c0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
271d0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 nt.)^.**.** [[SQ
271e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
271f0 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 ER_DEPTH]] ^(<dt
27200 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 >SQLITE_LIMIT_TR
27210 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e IGGER_DEPTH</dt>
27220 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
27230 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 mum depth of rec
27240 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 ursion for trigg
27250 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ers.</dd>)^.**.*
27260 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
27270 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d _WORKER_THREADS]
27280 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
27290 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 IMIT_WORKER_THRE
272a0 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ADS</dt>.** <dd>
272b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
272c0 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 er of auxiliary
272d0 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 worker threads t
272e0 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 hat a single.**
272f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
27300 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c ent] may start.<
27310 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a /dd>)^.** </dl>.
27320 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
27330 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 E_LIMIT_LENGTH
27340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
27350 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
27360 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e TE_LIMIT_SQL_LEN
27370 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 GTH
27380 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
27390 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
273a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
273b0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
273c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
273d0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 DEPTH
273e0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
273f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
27400 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 OUND_SELECT
27410 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 4.#define
27420 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
27430 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 E_OP
27440 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 5.#define
27450 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 SQLITE_LIMIT_FU
27460 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 NCTION_ARG
27470 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 6.#defin
27480 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 e SQLITE_LIMIT_A
27490 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 TTACHED
274a0 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 7.#defi
274b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
274c0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
274d0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 GTH 8.#def
274e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
274f0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
27500 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 9.#de
27510 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
27520 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 T_TRIGGER_DEPTH
27530 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 10.#d
27540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
27550 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 IT_WORKER_THREAD
27560 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a S 11..
27570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
27580 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c Compiling An SQL
27590 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 Statement.** KE
275a0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 YWORDS: {SQL sta
275b0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d tement compiler}
275c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
275d0 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 te3.** CONSTRUCT
275e0 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OR: sqlite3_stmt
275f0 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 .**.** To execut
27600 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 e an SQL query,
27610 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 it must first be
27620 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 compiled into a
27630 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 byte-code.** pr
27640 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 ogram using one
27650 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
27660 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 s..**.** The fir
27670 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 st argument, "db
27680 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 ", is a [databas
27690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 e connection] ob
276a0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a tained from a.**
276b0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 prior successfu
276c0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
276d0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
276e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
276f0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f or.** [sqlite3_o
27700 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 pen16()]. The d
27710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
27720 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 on must not have
27730 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a been closed..**
27740 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
27750 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c rgument, "zSql",
27760 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e is the statemen
27770 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
27780 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 , encoded.** as
27790 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
277a0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c UTF-16. The sql
277b0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 ite3_prepare() a
277c0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
277d0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 re_v2().** inter
277e0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c faces use UTF-8,
277f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
27800 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c pare16() and sql
27810 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
27820 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 2().** use UTF-1
27830 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 6..**.** ^If the
27840 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 nByte argument
27850 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
27860 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 n zSql is read u
27870 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 p to the.** firs
27880 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f t zero terminato
27890 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 r. ^If nByte is
278a0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 positive, then i
278b0 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 t is the.** numb
278c0 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 er of bytes read
278d0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 from zSql. ^If
278e0 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 nByte is zero,
278f0 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 then no prepared
27900 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 .** statement is
27910 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 generated..** I
27920 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f f the caller kno
27930 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 ws that the supp
27940 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e lied string is n
27950 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 ul-terminated, t
27960 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 hen.** there is
27970 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 a small performa
27980 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f nce advantage to
27990 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 passing an nByt
279a0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 e parameter that
279b0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 .** is the numbe
279c0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
279d0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c e input string <
279e0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a i>including</i>.
279f0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 ** the nul-termi
27a00 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 nator..**.** ^If
27a10 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e pzTail is not N
27a20 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c ULL then *pzTail
27a30 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e is made to poin
27a40 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 t to the first b
27a50 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 yte.** past the
27a60 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 end of the first
27a70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
27a80 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 n zSql. These r
27a90 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 outines only.**
27aa0 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 compile the firs
27ab0 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a t statement in z
27ac0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 Sql, so *pzTail
27ad0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 is left pointing
27ae0 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 to.** what rema
27af0 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a ins uncompiled..
27b00 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 **.** ^*ppStmt i
27b10 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 s left pointing
27b20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 to a compiled [p
27b30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
27b40 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a t] that can be.*
27b50 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 * executed using
27b60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
27b70 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 ]. ^If there is
27b80 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 an error, *ppSt
27b90 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 mt is set.** to
27ba0 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 NULL. ^If the i
27bb0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 nput text contai
27bc0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 ns no SQL (if th
27bd0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d e input is an em
27be0 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 pty.** string or
27bf0 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e a comment) then
27c00 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 *ppStmt is set
27c10 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 to NULL..** The
27c20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 calling procedur
27c30 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 e is responsible
27c40 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 for deleting th
27c50 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 e compiled.** SQ
27c60 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e L statement usin
27c70 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
27c80 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 ize()] after it
27c90 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
27ca0 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 h it..** ppStmt
27cb0 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e may not be NULL.
27cc0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 .**.** ^On succe
27cd0 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f ss, the sqlite3_
27ce0 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 prepare() family
27cf0 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 of routines ret
27d00 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b urn [SQLITE_OK];
27d10 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e .** otherwise an
27d20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
27d30 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
27d40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 The sqlite3_pre
27d50 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 pare_v2() and sq
27d60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
27d70 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 v2() interfaces
27d80 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 are.** recommend
27d90 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 ed for all new p
27da0 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f rograms. The two
27db0 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 older interface
27dc0 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a s are retained.*
27dd0 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 * for backwards
27de0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 compatibility, b
27df0 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 ut their use is
27e00 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 discouraged..**
27e10 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 ^In the "v2" int
27e20 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 erfaces, the pre
27e30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a pared statement.
27e40 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 ** that is retur
27e50 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 ned (the [sqlite
27e60 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 3_stmt] object)
27e70 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 contains a copy
27e80 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e of the.** origin
27e90 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 al SQL text. Thi
27ea0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 s causes the [sq
27eb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e lite3_step()] in
27ec0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 terface to.** be
27ed0 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 have differently
27ee0 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a in three ways:.
27ef0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c **.** <ol>.** <l
27f00 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 i>.** ^If the da
27f10 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 tabase schema ch
27f20 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f anges, instead o
27f30 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c f returning [SQL
27f40 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 ITE_SCHEMA] as i
27f50 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 t.** always used
27f60 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 to do, [sqlite3
27f70 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 _step()] will au
27f80 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f tomatically reco
27f90 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a mpile the SQL.**
27fa0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
27fb0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 ry to run it aga
27fc0 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b in. As many as [
27fd0 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d SQLITE_MAX_SCHEM
27fe0 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 A_RETRY].** retr
27ff0 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 ies will occur b
28000 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 efore sqlite3_st
28010 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e ep() gives up an
28020 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 d returns an err
28030 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a or..** </li>.**.
28040 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e ** <li>.** ^When
28050 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
28060 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
28070 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f )] will return o
28080 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c ne of the detail
28090 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 ed.** [error cod
280a0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 es] or [extended
280b0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 error codes].
280c0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 ^The legacy beha
280d0 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a vior was that.**
280e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
280f0 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 ] would only ret
28100 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 urn a generic [S
28110 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 QLITE_ERROR] res
28120 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 ult code.** and
28130 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
28140 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 would have to ma
28150 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c ke a second call
28160 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
28170 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 et()].** in orde
28180 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e r to find the un
28190 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f derlying cause o
281a0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 f the problem. W
281b0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 ith the "v2" pre
281c0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 pare.** interfac
281d0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 es, the underlyi
281e0 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 ng reason for th
281f0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 e error is retur
28200 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e ned immediately.
28210 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 .** </li>.**.**
28220 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 <li>.** ^If the
28230 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 specific value b
28240 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 ound to [paramet
28250 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 er | host parame
28260 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 ter] in the .**
28270 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 WHERE clause mig
28280 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 ht influence the
28290 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 choice of query
282a0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 plan for a stat
282b0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 ement,.** then t
282c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c he statement wil
282d0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c l be automatical
282e0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 ly recompiled, a
282f0 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 s if there had b
28300 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 een .** a schema
28310 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 change, on the
28320 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f first [sqlite3_
28330 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c step()] call fol
28340 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 lowing any chang
28350 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c e.** to the [sql
28360 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c ite3_bind_text |
28370 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 bindings] of th
28380 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 at [parameter].
28390 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 .** ^The specifi
283a0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 c value of WHERE
283b0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 -clause [paramet
283c0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 er] might influe
283d0 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 nce the .** choi
283e0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e ce of query plan
283f0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
28400 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 r is the left-ha
28410 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 nd side of a [LI
28420 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d KE].** or [GLOB]
28430 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 operator or if
28440 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 the parameter is
28450 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 compared to an
28460 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a indexed column.*
28470 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 * and the [SQLIT
28480 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 E_ENABLE_STAT3]
28490 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
284a0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a ion is enabled..
284b0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c ** </li>.** </ol
284c0 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 >.*/.SQLITE_API
284d0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
284e0 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 LL sqlite3_prepa
284f0 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 re(. sqlite3 *d
28500 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
28510 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
28520 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
28530 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
28540 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
28550 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f UTF-8 encoded */
28560 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
28570 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
28580 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
28590 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
285a0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
285b0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
285c0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
285d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
285e0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 char **pzTail
285f0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
28600 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
28610 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
28620 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
28630 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
28640 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
28650 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
28660 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
28670 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
28680 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
28690 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
286a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
286b0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f UTF-8 encoded */
286c0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
286d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
286e0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
286f0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
28700 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
28710 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
28720 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
28730 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
28740 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 char **pzTail
28750 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
28760 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
28770 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
28780 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
28790 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
287a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
287b0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 6(. sqlite3 *db
287c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
287d0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
287e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
287f0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
28800 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
28810 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
28820 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
28830 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
28840 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
28850 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
28860 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
28870 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
28880 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
28890 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
288a0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
288b0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
288c0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
288d0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
288e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
288f0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
28900 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
28910 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 6_v2(. sqlite3
28920 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
28930 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
28940 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
28950 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 id *zSql,
28960 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
28970 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 , UTF-16 encoded
28980 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
28990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
289a0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
289b0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
289c0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
289d0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
289e0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
289f0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
28a00 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c st void **pzTail
28a10 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
28a20 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
28a30 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
28a40 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
28a50 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 3REF: Retrieving
28a60 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a Statement SQL.*
28a70 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
28a80 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
28a90 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e is interface can
28aa0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 be used to retr
28ab0 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 ieve a saved cop
28ac0 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 y of the origina
28ad0 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 l.** SQL text us
28ae0 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b ed to create a [
28af0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
28b00 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 nt] if that stat
28b10 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d ement was.** com
28b20 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 piled using eith
28b30 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 er [sqlite3_prep
28b40 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 are_v2()] or [sq
28b50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
28b60 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 v2()]..*/.SQLITE
28b70 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
28b80 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
28b90 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 sqlite3_sql(sqli
28ba0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
28bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
28bc0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
28bd0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
28be0 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 Writes The Data
28bf0 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 base.** METHOD:
28c00 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
28c10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
28c20 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 stmt_readonly(X)
28c30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
28c40 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 ns true (non-zer
28c50 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c o) if.** and onl
28c60 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 y if the [prepar
28c70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 ed statement] X
28c80 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 makes no direct
28c90 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 changes to.** th
28ca0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
28cb0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a database file..
28cc0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
28cd0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
28ce0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
28cf0 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 ns] or.** [virtu
28d00 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 al tables] might
28d10 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 change the data
28d20 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 base indirectly
28d30 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 as a side effect
28d40 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 . .** ^(For exa
28d50 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c mple, if an appl
28d60 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 ication defines
28d70 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c a function "eval
28d80 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c ()" that .** cal
28d90 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ls [sqlite3_exec
28da0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f ()], then the fo
28db0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 llowing SQL stat
28dc0 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 ement would.** c
28dd0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
28de0 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 se file through
28df0 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a side-effects:.**
28e00 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
28e10 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 <pre>.** SELE
28e20 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 CT eval('DELETE
28e30 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 FROM t1') FROM t
28e40 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 2;.** </pre></bl
28e50 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
28e60 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 But because the
28e70 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
28e80 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e nt does not chan
28e90 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
28ea0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 file.** directly
28eb0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 , sqlite3_stmt_r
28ec0 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 eadonly() would
28ed0 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 still return tru
28ee0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e e.)^.**.** ^Tran
28ef0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 saction control
28f00 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 statements such
28f10 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d as [BEGIN], [COM
28f20 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d MIT], [ROLLBACK]
28f30 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d ,.** [SAVEPOINT]
28f40 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 , and [RELEASE]
28f50 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 cause sqlite3_st
28f60 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f mt_readonly() to
28f70 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a return true,.**
28f80 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 since the state
28f90 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 ments themselves
28fa0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 do not actually
28fb0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 modify the data
28fc0 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 base but.** rath
28fd0 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 er they control
28fe0 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 the timing of wh
28ff0 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 en other stateme
29000 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a nts modify the .
29010 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 ** database. ^T
29020 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 he [ATTACH] and
29030 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 [DETACH] stateme
29040 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a nts also cause.*
29050 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 * sqlite3_stmt_r
29060 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 eadonly() to ret
29070 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 urn true since,
29080 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 while those stat
29090 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 ements.** change
290a0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
290b0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 on of a database
290c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 connection, the
290d0 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a y do not make .*
290e0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 * changes to the
290f0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
29100 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f database files o
29110 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 n disk..*/.SQLIT
29120 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
29130 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
29140 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 _stmt_readonly(s
29150 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
29160 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
29170 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
29180 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 If A Prepared St
29190 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e atement Has Been
291a0 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 Reset.** METHOD
291b0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
291c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
291d0 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 3_stmt_busy(S) i
291e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
291f0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 true (non-zero)
29200 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 if the.** [prep
29210 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
29220 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 S has been stepp
29230 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 ed at least once
29240 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 using .** [sqli
29250 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 te3_step(S)] but
29260 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 has not run to
29270 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f completion and/o
29280 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 r has not .** be
29290 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b en reset using [
292a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
292b0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 ]. ^The sqlite3
292c0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a _stmt_busy(S).**
292d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
292e0 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 ns false if S is
292f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
29300 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 If S is not a
29310 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 .** NULL pointer
29320 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f and is not a po
29330 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 inter to a valid
29340 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
29350 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c ment].** object,
29360 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
29370 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 or is undefined
29380 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 and probably und
29390 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 esirable..**.**
293a0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 This interface c
293b0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f an be used in co
293c0 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 mbination [sqlit
293d0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a e3_next_stmt()].
293e0 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c ** to locate all
293f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
29400 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 ents associated
29410 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 with a database
29420 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 .** connection t
29430 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 hat are in need
29440 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 of being reset.
29450 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 This can be use
29460 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c d,.** for exampl
29470 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 e, in diagnostic
29480 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 routines to sea
29490 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 rch for prepared
294a0 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 .** statements
294b0 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 that are holding
294c0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f a transaction o
294d0 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 pen..*/.SQLITE_A
294e0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
294f0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 DCALL sqlite3_st
29500 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f mt_busy(sqlite3_
29510 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
29520 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 API3REF: Dynamic
29530 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 ally Typed Value
29540 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f Object.** KEYWO
29550 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 RDS: {protected
29560 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b sqlite3_value} {
29570 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
29580 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a te3_value}.**.**
29590 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 SQLite uses the
295a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
295b0 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 bject to represe
295c0 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a nt all values.**
295d0 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f that can be sto
295e0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 red in a databas
295f0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 e table. SQLite
29600 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 uses dynamic typ
29610 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 ing.** for the v
29620 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e alues it stores.
29630 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 ^Values stored
29640 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 in sqlite3_valu
29650 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e e objects.** can
29660 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c be integers, fl
29670 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
29680 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c ues, strings, BL
29690 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a OBs, or NULL..**
296a0 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 .** An sqlite3_v
296b0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 alue object may
296c0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 be either "prote
296d0 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 cted" or "unprot
296e0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 ected"..** Some
296f0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 interfaces requi
29700 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 re a protected s
29710 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f qlite3_value. O
29720 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a ther interfaces.
29730 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 ** will accept e
29740 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 ither a protecte
29750 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 d or an unprotec
29760 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
29770 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 e..** Every inte
29780 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 rface that accep
29790 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ts sqlite3_value
297a0 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 arguments speci
297b0 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 fies.** whether
297c0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 or not it requir
297d0 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 es a protected s
297e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 qlite3_value. T
297f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 he.** [sqlite3_v
29800 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 alue_dup()] inte
29810 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
29820 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 d to construct a
29830 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 new .** protect
29840 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
29850 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 from an unprote
29860 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
29870 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 ue..**.** The te
29880 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 rms "protected"
29890 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 and "unprotected
298a0 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 " refer to wheth
298b0 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d er or not.** a m
298c0 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 utex is held. A
298d0 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 n internal mutex
298e0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 is held for a p
298f0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
29900 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
29910 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 but no mutex is
29920 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 held for an unp
29930 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
29940 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
29950 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 . If SQLite is
29960 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 compiled to be s
29970 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a ingle-threaded.*
29980 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f * (with [SQLITE_
29990 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e THREADSAFE=0] an
299a0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f d with [sqlite3_
299b0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 threadsafe()] re
299c0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 turning 0).** or
299d0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 if SQLite is ru
299e0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 n in one of redu
299f0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 ced mutex modes
29a00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
29a10 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
29a20 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 or [SQLITE_CONF
29a30 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a IG_MULTITHREAD].
29a40 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 ** then there is
29a50 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 no distinction
29a60 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 between protecte
29a70 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 d and unprotecte
29a80 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
29a90 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 ue objects and t
29aa0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 hey can be used
29ab0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e interchangeably.
29ac0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f However,.** fo
29ad0 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 r maximum code p
29ae0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 ortability it is
29af0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 recommended tha
29b00 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a t applications.*
29b10 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 * still make the
29b20 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
29b30 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 ween protected a
29b40 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a nd unprotected.*
29b50 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
29b60 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 objects even whe
29b70 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 n not strictly r
29b80 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e equired..**.** ^
29b90 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
29ba0 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 e objects that a
29bb0 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 re passed as par
29bc0 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 ameters into the
29bd0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
29be0 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 on of [applicati
29bf0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
29c00 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 unctions] are pr
29c10 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 otected..** ^The
29c20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
29c30 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
29c40 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
29c50 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
29c60 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a unprotected..**
29c70 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c Unprotected sql
29c80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
29c90 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 ts may only be u
29ca0 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c sed with.** [sql
29cb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
29cc0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
29cd0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 3_bind_value()].
29ce0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
29cf0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 _value_blob | sq
29d00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 lite3_value_type
29d10 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a ()] family of.**
29d20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 interfaces requ
29d30 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 ire protected sq
29d40 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
29d50 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 cts..*/.typedef
29d60 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 struct Mem sqlit
29d70 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a e3_value;../*.**
29d80 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 CAPI3REF: SQL F
29d90 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 unction Context
29da0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 Object.**.** The
29db0 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 context in whic
29dc0 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f h an SQL functio
29dd0 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 n executes is st
29de0 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 ored in an.** sq
29df0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 lite3_context ob
29e00 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 ject. ^A pointe
29e10 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f r to an sqlite3_
29e20 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a context object.*
29e30 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 * is always firs
29e40 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b t parameter to [
29e50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
29e60 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
29e70 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 s]..** The appli
29e80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
29e90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c QL function impl
29ea0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 ementation will
29eb0 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 pass this.** poi
29ec0 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 nter through int
29ed0 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 o calls to [sqli
29ee0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c te3_result_int |
29ef0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 sqlite3_result(
29f00 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
29f10 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
29f20 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 t()], [sqlite3_u
29f30 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 ser_data()],.**
29f40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 [sqlite3_context
29f50 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b _db_handle()], [
29f60 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
29f70 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f ata()],.** and/o
29f80 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 r [sqlite3_set_a
29f90 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 uxdata()]..*/.ty
29fa0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
29fb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c ite3_context sql
29fc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f ite3_context;../
29fd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 *.** CAPI3REF: B
29fe0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f inding Values To
29ff0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
2a000 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ents.** KEYWORDS
2a010 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 : {host paramete
2a020 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 r} {host paramet
2a030 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d ers} {host param
2a040 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 eter name}.** KE
2a050 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 YWORDS: {SQL par
2a060 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 ameter} {SQL par
2a070 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 ameters} {parame
2a080 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 ter binding}.**
2a090 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
2a0a0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 stmt.**.** ^(In
2a0b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
2a0c0 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 t text input to
2a0d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2a0e0 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 _v2()] and its v
2a0f0 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 ariants,.** lite
2a100 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c rals may be repl
2a110 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d aced by a [param
2a120 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 eter] that match
2a130 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 es one of follow
2a140 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 ing.** templates
2a150 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
2a160 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 <li> ?.** <li>
2a170 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a ?NNN.** <li> :
2a180 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 VVV.** <li> @VV
2a190 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a V.** <li> $VVV.
2a1a0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </ul>.**.** I
2a1b0 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 n the templates
2a1c0 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 above, NNN repre
2a1d0 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 sents an integer
2a1e0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 literal,.** and
2a1f0 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 VVV represents
2a200 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 an alphanumeric
2a210 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e identifier.)^ ^
2a220 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 The values of th
2a230 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ese.** parameter
2a240 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 s (also called "
2a250 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e host parameter n
2a260 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 ames" or "SQL pa
2a270 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 rameters").** ca
2a280 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 n be set using t
2a290 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
2a2a0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 *() routines def
2a2b0 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a ined here..**.**
2a2c0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
2a2d0 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 ment to the sqli
2a2e0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
2a2f0 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a tines is always.
2a300 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
2a310 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
2a320 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e t] object return
2a330 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 ed from.** [sqli
2a340 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2a350 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
2a360 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 s..**.** ^The se
2a370 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
2a380 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 the index of th
2a390 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 e SQL parameter
2a3a0 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 to be set..** ^T
2a3b0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 he leftmost SQL
2a3c0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e parameter has an
2a3d0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 index of 1. ^W
2a3e0 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d hen the same nam
2a3f0 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 ed.** SQL parame
2a400 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 ter is used more
2a410 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f than once, seco
2a420 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e nd and subsequen
2a430 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 t.** occurrences
2a440 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 have the same i
2a450 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 ndex as the firs
2a460 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a t occurrence..**
2a470 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 ^The index for
2a480 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 named parameters
2a490 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 can be looked u
2a4a0 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b p using the.** [
2a4b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2a4c0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 ameter_index()]
2a4d0 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 API if desired.
2a4e0 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 ^The index.** f
2a4f0 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 or "?NNN" parame
2a500 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 ters is the valu
2a510 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 e of NNN..** ^Th
2a520 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 e NNN value must
2a530 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e be between 1 an
2a540 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c d the [sqlite3_l
2a550 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d imit()].** param
2a560 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d eter [SQLITE_LIM
2a570 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
2a580 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c ER] (default val
2a590 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 ue: 999)..**.**
2a5a0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d ^The third argum
2a5b0 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 ent is the value
2a5c0 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 to bind to the
2a5d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 parameter..** ^I
2a5e0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 f the third para
2a5f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
2a600 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 _bind_text() or
2a610 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2a620 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 t16().** or sqli
2a630 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 te3_bind_blob()
2a640 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
2a650 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 r then the fourt
2a660 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 h parameter.** i
2a670 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 s ignored and th
2a680 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 e end result is
2a690 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 the same as sqli
2a6a0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e te3_bind_null().
2a6b0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 .**.** ^(In thos
2a6c0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 e routines that
2a6d0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 have a fourth ar
2a6e0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 gument, its valu
2a6f0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
2a700 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
2a710 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 he parameter. T
2a720 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 o be clear: the
2a730 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 value is the.**
2a740 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 number of <u>byt
2a750 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 es</u> in the va
2a760 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d lue, not the num
2a770 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
2a780 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 s.)^.** ^If the
2a790 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
2a7a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2a7b0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 _text() or sqlit
2a7c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 e3_bind_text16()
2a7d0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c .** is negative,
2a7e0 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 then the length
2a7f0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 of the string i
2a800 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
2a810 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 of bytes up to t
2a820 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 he first zero te
2a830 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 rminator..** If
2a840 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
2a850 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
2a860 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e bind_blob() is n
2a870 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a egative, then.**
2a880 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
2a890 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 undefined..** I
2a8a0 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 f a non-negative
2a8b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
2a8c0 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f r is provided to
2a8d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
2a8e0 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 xt().** or sqlit
2a8f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 e3_bind_text16()
2a900 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
2a910 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a _text64() then.*
2a920 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 * that parameter
2a930 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 must be the byt
2a940 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 e offset.** wher
2a950 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e e the NUL termin
2a960 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 ator would occur
2a970 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 assuming the st
2a980 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a ring were NUL.**
2a990 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 terminated. If
2a9a0 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 any NUL charact
2a9b0 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 ers occur at byt
2a9c0 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 e offsets less t
2a9d0 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 han .** the valu
2a9e0 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 e of the fourth
2a9f0 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 parameter then t
2aa00 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 he resulting str
2aa10 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a ing value will.*
2aa20 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 * contain embedd
2aa30 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 ed NULs. The re
2aa40 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 sult of expressi
2aa50 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 ons involving st
2aa60 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d rings.** with em
2aa70 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 bedded NULs is u
2aa80 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
2aa90 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d ^The fifth argum
2aaa0 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 ent to the BLOB
2aab0 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 and string bindi
2aac0 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a ng interfaces.**
2aad0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 is a destructor
2aae0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 used to dispose
2aaf0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a of the BLOB or.
2ab00 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 ** string after
2ab10 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 SQLite has finis
2ab20 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 hed with it. ^T
2ab30 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 he destructor is
2ab40 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 called.** to di
2ab50 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f spose of the BLO
2ab60 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e B or string even
2ab70 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 if the call to
2ab80 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a bind API fails..
2ab90 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 ** ^If the fifth
2aba0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 argument is.**
2abb0 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 the special valu
2abc0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 e [SQLITE_STATIC
2abd0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 ], then SQLite a
2abe0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a ssumes that the.
2abf0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 ** information i
2ac00 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d s in static, unm
2ac10 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 anaged space and
2ac20 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
2ac30 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e o be freed..** ^
2ac40 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 If the fifth arg
2ac50 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 ument has the va
2ac60 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e lue [SQLITE_TRAN
2ac70 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 SIENT], then.**
2ac80 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 SQLite makes its
2ac90 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 own private cop
2aca0 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d y of the data im
2acb0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 mediately, befor
2acc0 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 e.** the sqlite3
2acd0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
2ace0 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a e returns..**.**
2acf0 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75 ^The sixth argu
2ad00 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
2ad10 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 bind_text64() mu
2ad20 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 st be one of.**
2ad30 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b [SQLITE_UTF8], [
2ad40 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b SQLITE_UTF16], [
2ad50 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c SQLITE_UTF16BE],
2ad60 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 or [SQLITE_UTF1
2ad70 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 6LE].** to speci
2ad80 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 fy the encoding
2ad90 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 of the text in t
2ada0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
2adb0 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 er. If.** the s
2adc0 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f ixth argument to
2add0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
2ade0 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e xt64() is not on
2adf0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f e of the.** allo
2ae00 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e wed values shown
2ae10 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 above, or if th
2ae20 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 e text encoding
2ae30 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 is different.**
2ae40 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e from the encodin
2ae50 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 g specified by t
2ae60 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 he sixth paramet
2ae70 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 er, then the beh
2ae80 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 avior.** is unde
2ae90 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
2aea0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a e sqlite3_bind_z
2aeb0 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e eroblob() routin
2aec0 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f e binds a BLOB o
2aed0 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a f length N that.
2aee0 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 ** is filled wit
2aef0 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 h zeroes. ^A ze
2af00 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 roblob uses a fi
2af10 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 xed amount of me
2af20 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e mory.** (just an
2af30 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 integer to hold
2af40 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 its size) while
2af50 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f it is being pro
2af60 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 cessed..** Zerob
2af70 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 lobs are intende
2af80 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c d to serve as pl
2af90 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 aceholders for B
2afa0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f LOBs whose.** co
2afb0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 ntent is later w
2afc0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 ritten using.**
2afd0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
2afe0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c en | incremental
2aff0 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 BLOB I/O] routi
2b000 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 nes..** ^A negat
2b010 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 ive value for th
2b020 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c e zeroblob resul
2b030 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e ts in a zero-len
2b040 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 gth BLOB..**.**
2b050 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 ^If any of the s
2b060 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
2b070 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
2b080 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 led with a NULL
2b090 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 pointer.** for t
2b0a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2b0b0 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 tement] or with
2b0c0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
2b0d0 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a ment for which.*
2b0e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
2b0f0 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c )] has been call
2b100 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 ed more recently
2b110 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 than [sqlite3_r
2b120 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e eset()],.** then
2b130 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 the call will r
2b140 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 eturn [SQLITE_MI
2b150 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 SUSE]. If any s
2b160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a qlite3_bind_().*
2b170 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 * routine is pas
2b180 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 sed a [prepared
2b190 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
2b1a0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a has been finaliz
2b1b0 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c ed, the.** resul
2b1c0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 t is undefined a
2b1d0 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d nd probably harm
2b1e0 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 ful..**.** ^Bind
2b1f0 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 ings are not cle
2b200 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c ared by the [sql
2b210 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f ite3_reset()] ro
2b220 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 utine..** ^Unbou
2b230 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 nd parameters ar
2b240 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 e interpreted as
2b250 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 NULL..**.** ^Th
2b260 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
2b270 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2b280 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
2b290 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a success or an.**
2b2a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
2b2b0 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 anything goes w
2b2c0 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 rong..** ^[SQLIT
2b2d0 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 E_TOOBIG] might
2b2e0 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 be returned if t
2b2f0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 he size of a str
2b300 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 ing or BLOB.** e
2b310 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d xceeds limits im
2b320 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 posed by [sqlite
2b330 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 3_limit]([SQLITE
2b340 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 _LIMIT_LENGTH])
2b350 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 or.** [SQLITE_MA
2b360 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b X_LENGTH]..** ^[
2b370 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 SQLITE_RANGE] is
2b380 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 returned if the
2b390 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e parameter.** in
2b3a0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 dex is out of ra
2b3b0 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e nge. ^[SQLITE_N
2b3c0 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 OMEM] is returne
2b3d0 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 d if malloc() fa
2b3e0 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ils..**.** See a
2b3f0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
2b400 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
2b410 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nt()],.** [sqlit
2b420 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2b430 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b r_name()], and [
2b440 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2b450 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
2b460 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2b470 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
2b480 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 L sqlite3_bind_b
2b490 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
2b4a0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f *, int, const vo
2b4b0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 id*, int n, void
2b4c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c (*)(void*));.SQL
2b4d0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
2b4e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2b4f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 e3_bind_blob64(s
2b500 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2b510 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 t, const void*,
2b520 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a sqlite3_uint64,.
2b530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2b540 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 void(*)(
2b550 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f void*));.SQLITE_
2b560 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
2b570 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 TDCALL sqlite3_b
2b580 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 ind_double(sqlit
2b590 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 e3_stmt*, int, d
2b5a0 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 ouble);.SQLITE_A
2b5b0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2b5c0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 DCALL sqlite3_bi
2b5d0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 nd_int(sqlite3_s
2b5e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b tmt*, int, int);
2b5f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2b600 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2b610 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 qlite3_bind_int6
2b620 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
2b630 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e int, sqlite3_in
2b640 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 t64);.SQLITE_API
2b650 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
2b660 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 ALL sqlite3_bind
2b670 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 _null(sqlite3_st
2b680 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 mt*, int);.SQLIT
2b690 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2b6a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2b6b0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 _bind_text(sqlit
2b6c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e e3_stmt*,int,con
2b6d0 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 st char*,int,voi
2b6e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 d(*)(void*));.SQ
2b6f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
2b700 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2b710 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
2b720 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2b730 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c nt, const void*,
2b740 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
2b750 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
2b760 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
2b770 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e CALL sqlite3_bin
2b780 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 d_text64(sqlite3
2b790 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
2b7a0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 st char*, sqlite
2b7b0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 3_uint64,.
2b7c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2b7d0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a void(*)(void*
2b7e0 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 ), unsigned char
2b7f0 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 encoding);.SQLI
2b800 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2b810 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2b820 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 3_bind_value(sql
2b830 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
2b840 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 const sqlite3_v
2b850 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
2b860 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2b870 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 DCALL sqlite3_bi
2b880 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 nd_zeroblob(sqli
2b890 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2b8a0 69 6e 74 20 6e 29 3b 0a 53 51 4c 49 54 45 5f 41 int n);.SQLITE_A
2b8b0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2b8c0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 DCALL sqlite3_bi
2b8d0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 nd_zeroblob64(sq
2b8e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2b8f0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 , sqlite3_uint64
2b900 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2b910 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 EF: Number Of SQ
2b920 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 L Parameters.**
2b930 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
2b940 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 stmt.**.** ^This
2b950 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
2b960 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 used to find the
2b970 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 number of [SQL
2b980 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 parameters].** i
2b990 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
2b9a0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 atement]. SQL p
2b9b0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f arameters are to
2b9c0 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 kens of the.** f
2b9d0 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c orm "?", "?NNN",
2b9e0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c ":AAA", "$AAA",
2b9f0 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 or "@AAA" that
2ba00 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 serve as.** plac
2ba10 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c eholders for val
2ba20 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 ues that are [sq
2ba30 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
2ba40 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 | bound].** to t
2ba50 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 he parameters at
2ba60 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a a later time..*
2ba70 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 *.** ^(This rout
2ba80 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 ine actually ret
2ba90 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f urns the index o
2baa0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 f the largest (r
2bab0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 ightmost).** par
2bac0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 ameter. For all
2bad0 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e forms except ?NN
2bae0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 N, this will cor
2baf0 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a respond to the.*
2bb00 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 * number of uniq
2bb10 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ue parameters.
2bb20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 If parameters of
2bb30 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 the ?NNN form a
2bb40 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 re used,.** ther
2bb50 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e e may be gaps in
2bb60 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a the list.)^.**.
2bb70 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
2bb80 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
2bb90 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
2bba0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2bbb0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
2bbc0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
2bbd0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2bbe0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
2bbf0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2bc00 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2bc10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2bc20 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 meter_count(sqli
2bc30 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
2bc40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d ** CAPI3REF: Nam
2bc50 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 e Of A Host Para
2bc60 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a meter.** METHOD:
2bc70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2bc80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2bc90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2bca0 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 name(P,N) interf
2bcb0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 ace returns.** t
2bcc0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e he name of the N
2bcd0 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 -th [SQL paramet
2bce0 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 er] in the [prep
2bcf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2bd00 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 P..** ^(SQL para
2bd10 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f meters of the fo
2bd20 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 rm "?NNN" or ":A
2bd30 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 AA" or "@AAA" or
2bd40 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 "$AAA".** have
2bd50 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 a name which is
2bd60 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e the string "?NNN
2bd70 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 " or ":AAA" or "
2bd80 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a @AAA" or "$AAA".
2bd90 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e ** respectively.
2bda0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 .** In other wor
2bdb0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 ds, the initial
2bdc0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 ":" or "$" or "@
2bdd0 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 " or "?".** is i
2bde0 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 ncluded as part
2bdf0 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a of the name.)^.*
2be00 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 * ^Parameters of
2be10 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 the form "?" wi
2be20 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e thout a followin
2be30 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e g integer have n
2be40 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 o name.** and ar
2be50 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 e referred to as
2be60 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 "nameless" or "
2be70 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 anonymous parame
2be80 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ters"..**.** ^Th
2be90 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 e first host par
2bea0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e ameter has an in
2beb0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e dex of 1, not 0.
2bec0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 .**.** ^If the v
2bed0 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 alue N is out of
2bee0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 range or if the
2bef0 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 N-th parameter
2bf00 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 is.** nameless,
2bf10 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 then NULL is ret
2bf20 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 urned. ^The ret
2bf30 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a urned string is.
2bf40 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 ** always in UTF
2bf50 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e -8 encoding even
2bf60 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 if the named pa
2bf70 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f rameter was.** o
2bf80 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 riginally specif
2bf90 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e ied as UTF-16 in
2bfa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2bfb0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 e16()] or.** [sq
2bfc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2bfd0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 v2()]..**.** See
2bfe0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
2bff0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
2c000 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 3_bind()],.** [s
2c010 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2c020 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 meter_count()],
2c030 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
2c040 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
2c050 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 ndex()]..*/.SQLI
2c060 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
2c070 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c r *SQLITE_STDCAL
2c080 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 L sqlite3_bind_p
2c090 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 arameter_name(sq
2c0a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2c0b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2c0c0 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 EF: Index Of A P
2c0d0 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 arameter With A
2c0e0 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 Given Name.** ME
2c0f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2c100 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e mt.**.** ^Return
2c110 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e the index of an
2c120 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 SQL parameter g
2c130 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 iven its name.
2c140 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 ^The.** index va
2c150 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 lue returned is
2c160 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 suitable for use
2c170 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a as the second.*
2c180 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b * parameter to [
2c190 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2c1a0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
2c1b0 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 ]. ^A zero.** i
2c1c0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f s returned if no
2c1d0 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 matching parame
2c1e0 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e ter is found. ^
2c1f0 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a The parameter.**
2c200 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 name must be gi
2c210 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 ven in UTF-8 eve
2c220 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 n if the origina
2c230 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 l statement.** w
2c240 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d as prepared from
2c250 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 UTF-16 text usi
2c260 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
2c270 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a are16_v2()]..**.
2c280 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
2c290 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
2c2a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
2c2b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2c2c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
2c2d0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 t()], and.** [sq
2c2e0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2c2f0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
2c300 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2c310 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2c320 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2c330 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c ameter_index(sql
2c340 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 ite3_stmt*, cons
2c350 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a t char *zName);.
2c360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2c370 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 Reset All Bindi
2c380 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 ngs On A Prepare
2c390 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d d Statement.** M
2c3a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2c3b0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 tmt.**.** ^Contr
2c3c0 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 ary to the intui
2c3d0 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 tion of many, [s
2c3e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2c3f0 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a does not reset.*
2c400 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 * the [sqlite3_b
2c410 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 ind_blob | bindi
2c420 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 ngs] on a [prepa
2c430 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
2c440 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 ** ^Use this rou
2c450 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c tine to reset al
2c460 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 l host parameter
2c470 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 s to NULL..*/.SQ
2c480 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
2c490 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2c4a0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
2c4b0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a gs(sqlite3_stmt*
2c4c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2c4d0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f EF: Number Of Co
2c4e0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c lumns In A Resul
2c4f0 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a t Set.** METHOD:
2c500 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2c510 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 .** ^Return the
2c520 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
2c530 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 s in the result
2c540 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 set returned by
2c550 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
2c560 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 statement]. ^Th
2c570 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
2c580 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 ns 0 if pStmt is
2c590 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 an SQL.** state
2c5a0 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e ment that does n
2c5b0 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 ot return data (
2c5c0 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b for example an [
2c5d0 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 UPDATE])..**.**
2c5e0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
2c5f0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d e3_data_count()]
2c600 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2c610 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
2c620 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e L sqlite3_column
2c630 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
2c640 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
2c650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
2c660 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 lumn Names In A
2c670 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 Result Set.** ME
2c680 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2c690 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 mt.**.** ^These
2c6a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
2c6b0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 the name assigne
2c6c0 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 d to a particula
2c6d0 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 r column.** in t
2c6e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 he result set of
2c6f0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 a [SELECT] stat
2c700 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c ement. ^The sql
2c710 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
2c720 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
2c730 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
2c740 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
2c750 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
2c760 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 ing.** and sqlit
2c770 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
2c780 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 () returns a poi
2c790 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 nter to a zero-t
2c7a0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
2c7b0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 -16 string. ^Th
2c7c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
2c7d0 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 r is the [prepar
2c7e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
2c7f0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 that implements
2c800 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 the [SELECT] st
2c810 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 atement. ^The se
2c820 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
2c830 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 s the.** column
2c840 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 number. ^The le
2c850 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 ftmost column is
2c860 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a number 0..**.**
2c870 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
2c880 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 tring pointer is
2c890 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 valid until eit
2c8a0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 her the [prepare
2c8b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
2c8c0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 is destroyed by
2c8d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2c8e0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 e()] or until th
2c8f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
2c900 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 utomatically.**
2c910 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 reprepared by th
2c920 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 e first call to
2c930 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2c940 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
2c950 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 r run.** or unti
2c960 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 l the next call
2c970 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f to.** sqlite3_co
2c980 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 lumn_name() or s
2c990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
2c9a0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 me16() on the sa
2c9b0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a me column..**.**
2c9c0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^If sqlite3_mal
2c9d0 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 loc() fails duri
2c9e0 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e ng the processin
2c9f0 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 g of either rout
2ca00 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d ine.** (for exam
2ca10 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e ple during a con
2ca20 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 version from UTF
2ca30 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 -8 to UTF-16) th
2ca40 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 en a.** NULL poi
2ca50 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 nter is returned
2ca60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d ..**.** ^The nam
2ca70 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f e of a result co
2ca80 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 lumn is the valu
2ca90 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c e of the "AS" cl
2caa0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 ause for.** that
2cab0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 column, if ther
2cac0 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 e is an AS claus
2cad0 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 e. If there is
2cae0 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 no AS clause.**
2caf0 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 then the name of
2cb00 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 the column is u
2cb10 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d nspecified and m
2cb20 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a ay change from.*
2cb30 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 * one release of
2cb40 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e SQLite to the n
2cb50 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ext..*/.SQLITE_A
2cb60 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 PI const char *S
2cb70 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2cb80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
2cb90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2cba0 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f int N);.SQLITE_
2cbb0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
2cbc0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2cbd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
2cbe0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
2cbf0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a t*, int N);../*.
2cc00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 ** CAPI3REF: Sou
2cc10 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 rce Of Data In A
2cc20 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a Query Result.**
2cc30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2cc40 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _stmt.**.** ^The
2cc50 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 se routines prov
2cc60 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 ide a means to d
2cc70 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 etermine the dat
2cc80 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e abase, table, an
2cc90 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d d.** table colum
2cca0 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 n that is the or
2ccb0 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 igin of a partic
2ccc0 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 ular result colu
2ccd0 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 mn in.** [SELECT
2cce0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 ] statement..**
2ccf0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 ^The name of the
2cd00 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 database or tab
2cd10 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e le or column can
2cd20 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a be returned as.
2cd30 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d ** either a UTF-
2cd40 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 8 or UTF-16 stri
2cd50 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 ng. ^The _datab
2cd60 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 ase_ routines re
2cd70 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 turn.** the data
2cd80 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f base name, the _
2cd90 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 table_ routines
2cda0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 return the table
2cdb0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 name, and.** th
2cdc0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e e origin_ routin
2cdd0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f es return the co
2cde0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 lumn name..** ^T
2cdf0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
2ce00 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 ng is valid unti
2ce10 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 l the [prepared
2ce20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 statement] is de
2ce30 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 stroyed.** using
2ce40 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2ce50 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 ze()] or until t
2ce60 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
2ce70 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a automatically.**
2ce80 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 reprepared by t
2ce90 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f he first call to
2cea0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2ceb0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c ] for a particul
2cec0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 ar run.** or unt
2ced0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f il the same info
2cee0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 rmation is reque
2cef0 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e sted.** again in
2cf00 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 a different enc
2cf10 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 oding..**.** ^Th
2cf20 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 e names returned
2cf30 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 are the origina
2cf40 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d l un-aliased nam
2cf50 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 es of the.** dat
2cf60 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e abase, table, an
2cf70 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 d column..**.**
2cf80 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
2cf90 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 ent to these int
2cfa0 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 erfaces is a [pr
2cfb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2cfc0 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e ]..** ^These fun
2cfd0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e ctions return in
2cfe0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
2cff0 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 the Nth result c
2d000 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 olumn returned b
2d010 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 y.** the stateme
2d020 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 nt, where N is t
2d030 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 he second functi
2d040 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 on argument..**
2d050 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 ^The left-most c
2d060 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 olumn is column
2d070 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 0 for these rout
2d080 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ines..**.** ^If
2d090 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 the Nth column r
2d0a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 eturned by the s
2d0b0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 tatement is an e
2d0c0 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 xpression or.**
2d0d0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 subquery and is
2d0e0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c not a column val
2d0f0 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 ue, then all of
2d100 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 these functions
2d110 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 return.** NULL.
2d120 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 ^These routine
2d130 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 might also retur
2d140 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f n NULL if a memo
2d150 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
2d160 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 ror.** occurs.
2d170 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 ^Otherwise, they
2d180 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 return the name
2d190 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 of the attached
2d1a0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
2d1b0 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 ,.** or column t
2d1c0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 hat query result
2d1d0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 column was extr
2d1e0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a acted from..**.*
2d1f0 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f * ^As with all o
2d200 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 ther SQLite APIs
2d210 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 , those whose na
2d220 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 mes end with "16
2d230 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d " return.** UTF-
2d240 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 16 encoded strin
2d250 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 gs and the other
2d260 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
2d270 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e n UTF-8..**.** ^
2d280 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f These APIs are o
2d290 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
2d2a0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 the library was
2d2b0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
2d2c0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e he.** [SQLITE_EN
2d2d0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 ABLE_COLUMN_META
2d2e0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 DATA] C-preproce
2d2f0 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a ssor symbol..**.
2d300 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 ** If two or mor
2d310 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f e threads call o
2d320 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 ne or more of th
2d330 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 ese routines aga
2d340 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a inst the same.**
2d350 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2d360 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 ent and column a
2d370 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 t the same time
2d380 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 then the results
2d390 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 are.** undefine
2d3a0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 d..**.** If two
2d3b0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 or more threads
2d3c0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 call one or more
2d3d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
2d3e0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d umn_database_nam
2d3f0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 e | column metad
2d400 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a ata interfaces].
2d410 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ** for the same
2d420 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2d430 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 ent] and result
2d440 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 column.** at the
2d450 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 same time then
2d460 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
2d470 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 undefined..*/.SQ
2d480 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
2d490 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 har *SQLITE_STDC
2d4a0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ALL sqlite3_colu
2d4b0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
2d4c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2d4d0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
2d4e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 const void *SQLI
2d4f0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2d500 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 e3_column_databa
2d510 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 se_name16(sqlite
2d520 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 3_stmt*,int);.SQ
2d530 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
2d540 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 har *SQLITE_STDC
2d550 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ALL sqlite3_colu
2d560 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 mn_table_name(sq
2d570 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2d580 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
2d590 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f st void *SQLITE_
2d5a0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
2d5b0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d column_table_nam
2d5c0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
2d5d0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 *,int);.SQLITE_A
2d5e0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 PI const char *S
2d5f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2d600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 lite3_column_ori
2d610 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 gin_name(sqlite3
2d620 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c _stmt*,int);.SQL
2d630 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
2d640 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 id *SQLITE_STDCA
2d650 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
2d660 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 n_origin_name16(
2d670 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2d680 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2d690 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 REF: Declared Da
2d6a0 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 tatype Of A Quer
2d6b0 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 y Result.** METH
2d6c0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2d6d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 .**.** ^(The fir
2d6e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
2d6f0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2d700 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 ement]..** If th
2d710 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 is statement is
2d720 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 a [SELECT] state
2d730 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 ment and the Nth
2d740 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a column of the.*
2d750 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c * returned resul
2d760 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 t set of that [S
2d770 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c ELECT] is a tabl
2d780 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e e column (not an
2d790 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f .** expression o
2d7a0 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e r subquery) then
2d7b0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 the declared ty
2d7c0 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a pe of the table.
2d7d0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 ** column is ret
2d7e0 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 urned.)^ ^If th
2d7f0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 e Nth column of
2d800 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 the result set i
2d810 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 s an.** expressi
2d820 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 on or subquery,
2d830 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e then a NULL poin
2d840 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ter is returned.
2d850 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 .** ^The returne
2d860 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 d string is alwa
2d870 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 ys UTF-8 encoded
2d880 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 ..**.** ^(For ex
2d890 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 ample, given the
2d8a0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 database schema
2d8b0 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 :.**.** CREATE T
2d8c0 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 ABLE t1(c1 VARIA
2d8d0 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 NT);.**.** and t
2d8e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 he following sta
2d8f0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d tement to be com
2d900 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c piled:.**.** SEL
2d910 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 ECT c1 + 1, c1 F
2d920 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 ROM t1;.**.** th
2d930 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 is routine would
2d940 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 return the stri
2d950 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 ng "VARIANT" for
2d960 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 the second resu
2d970 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d lt.** column (i=
2d980 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 =1), and a NULL
2d990 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 pointer for the
2d9a0 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c first result col
2d9b0 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a umn (i==0).)^.**
2d9c0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 .** ^SQLite uses
2d9d0 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d dynamic run-tim
2d9e0 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a e typing. ^So j
2d9f0 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f ust because a co
2da00 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 lumn.** is decla
2da10 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 red to contain a
2da20 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 particular type
2da30 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 does not mean t
2da40 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 hat the.** data
2da50 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 stored in that c
2da60 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 olumn is of the
2da70 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 declared type.
2da80 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 SQLite is.** str
2da90 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 ongly typed, but
2daa0 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 the typing is d
2dab0 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 ynamic not stati
2dac0 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 c. ^Type.** is
2dad0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
2dae0 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 individual value
2daf0 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 s, not with the
2db00 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 containers.** us
2db10 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 ed to hold those
2db20 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 values..*/.SQLI
2db30 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
2db40 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c r *SQLITE_STDCAL
2db50 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e L sqlite3_column
2db60 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 _decltype(sqlite
2db70 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 3_stmt*,int);.SQ
2db80 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
2db90 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 oid *SQLITE_STDC
2dba0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ALL sqlite3_colu
2dbb0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 mn_decltype16(sq
2dbc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2dbd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2dbe0 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 F: Evaluate An S
2dbf0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 QL Statement.**
2dc00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
2dc10 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 stmt.**.** After
2dc20 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2dc30 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e tement] has been
2dc40 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 prepared using
2dc50 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 either.** [sqlit
2dc60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2dc70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
2dc80 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
2dc90 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 one of the legac
2dca0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 y.** interfaces
2dcb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2dcc0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2dcd0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 prepare16()], th
2dce0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d is function.** m
2dcf0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e ust be called on
2dd00 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 e or more times
2dd10 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 to evaluate the
2dd20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a statement..**.**
2dd30 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 The details of
2dd40 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
2dd50 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 the sqlite3_step
2dd60 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 () interface dep
2dd70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 end.** on whethe
2dd80 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 r the statement
2dd90 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 was prepared usi
2dda0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 ng the newer "v2
2ddb0 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b " interface.** [
2ddc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2ddd0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
2dde0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
2ddf0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 )] or the older
2de00 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 legacy.** interf
2de10 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ace [sqlite3_pre
2de20 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c pare()] and [sql
2de30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
2de40 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 ]. The use of t
2de50 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 he.** new "v2" i
2de60 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f nterface is reco
2de70 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 mmended for new
2de80 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 applications but
2de90 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
2dea0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f nterface will co
2deb0 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 ntinue to be sup
2dec0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 ported..**.** ^I
2ded0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 n the legacy int
2dee0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 erface, the retu
2def0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 rn value will be
2df00 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
2df10 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 BUSY],.** [SQLIT
2df20 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 E_DONE], [SQLITE
2df30 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 _ROW], [SQLITE_E
2df40 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 RROR], or [SQLIT
2df50 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 E_MISUSE]..** ^W
2df60 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 ith the "v2" int
2df70 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 erface, any of t
2df80 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 he other [result
2df90 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 codes] or.** [e
2dfa0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
2dfb0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 odes] might be r
2dfc0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e eturned as well.
2dfd0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f .**.** ^[SQLITE_
2dfe0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 BUSY] means that
2dff0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e the database en
2e000 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 gine was unable
2e010 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a to acquire the.*
2e020 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 * database locks
2e030 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 it needs to do
2e040 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 its job. ^If th
2e050 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
2e060 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 [COMMIT].** or
2e070 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f occurs outside o
2e080 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 f an explicit tr
2e090 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 ansaction, then
2e0a0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 you can retry th
2e0b0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 e.** statement.
2e0c0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e If the statemen
2e0d0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d t is not a [COMM
2e0e0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 IT] and occurs w
2e0f0 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c ithin an.** expl
2e100 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e icit transaction
2e110 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 then you should
2e120 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 rollback the tr
2e130 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 ansaction before
2e140 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a .** continuing..
2e150 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 **.** ^[SQLITE_D
2e160 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 ONE] means that
2e170 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 the statement ha
2e180 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 s finished execu
2e190 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 ting.** successf
2e1a0 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 ully. sqlite3_s
2e1b0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 tep() should not
2e1c0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e be called again
2e1d0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c on this virtual
2e1e0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 .** machine with
2e1f0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e out first callin
2e200 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
2e210 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 ()] to reset the
2e220 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 virtual.** mach
2e230 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 ine back to its
2e240 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a initial state..*
2e250 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c *.** ^If the SQL
2e260 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 statement being
2e270 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e executed return
2e280 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e s any data, then
2e290 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a [SQLITE_ROW].**
2e2a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 is returned eac
2e2b0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 h time a new row
2e2c0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 of data is read
2e2d0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 y for processing
2e2e0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 by the.** calle
2e2f0 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 r. The values ma
2e300 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 y be accessed us
2e310 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 ing the [column
2e320 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 access functions
2e330 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 ]..** sqlite3_st
2e340 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 ep() is called a
2e350 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 gain to retrieve
2e360 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 the next row of
2e370 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 data..**.** ^[S
2e380 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 QLITE_ERROR] mea
2e390 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 ns that a run-ti
2e3a0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 me error (such a
2e3b0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a s a constraint.*
2e3c0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 * violation) has
2e3d0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 occurred. sqli
2e3e0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c te3_step() shoul
2e3f0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 d not be called
2e400 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 again on.** the
2e410 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 VM. More informa
2e420 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e tion may be foun
2e430 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 d by calling [sq
2e440 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e lite3_errmsg()].
2e450 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 .** ^With the le
2e460 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
2e470 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 a more specific
2e480 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 error code (for
2e490 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c example,.** [SQL
2e4a0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 ITE_INTERRUPT],
2e4b0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c [SQLITE_SCHEMA],
2e4c0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 [SQLITE_CORRUPT
2e4d0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 ], and so forth)
2e4e0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 .** can be obtai
2e4f0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b ned by calling [
2e500 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2e510 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 on the.** [prep
2e520 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
2e530 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 ^In the "v2" i
2e540 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 nterface,.** the
2e550 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 more specific e
2e560 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 rror code is ret
2e570 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 urned directly b
2e580 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 y sqlite3_step()
2e590 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ..**.** [SQLITE_
2e5a0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 MISUSE] means th
2e5b0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 at the this rout
2e5c0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 ine was called i
2e5d0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a nappropriately..
2e5e0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 ** Perhaps it wa
2e5f0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 s called on a [p
2e600 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2e610 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 t] that has.** a
2e620 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c lready been [sql
2e630 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 ite3_finalize |
2e640 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e finalized] or on
2e650 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a one that had.**
2e660 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 previously retu
2e670 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 rned [SQLITE_ERR
2e680 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 OR] or [SQLITE_D
2e690 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 ONE]. Or it cou
2e6a0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 ld.** be the cas
2e6b0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 e that the same
2e6c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2e6d0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 ion is being use
2e6e0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d d by two or.** m
2e6f0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 ore threads at t
2e700 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 he same moment i
2e710 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f n time..**.** Fo
2e720 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f r all versions o
2e730 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 f SQLite up to a
2e740 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 nd including 3.6
2e750 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f .23.1, a call to
2e760 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
2e770 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 et()] was requir
2e780 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 ed after sqlite3
2e790 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 _step() returned
2e7a0 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 anything.** oth
2e7b0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
2e7c0 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 ROW] before any
2e7d0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 subsequent invoc
2e7e0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 ation of.** sqli
2e7f0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 te3_step(). Fai
2e800 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 lure to reset th
2e810 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
2e820 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b ment using .** [
2e830 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2e840 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e would result in
2e850 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 an [SQLITE_MISU
2e860 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a SE] return from.
2e870 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
2e880 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 ). But after ve
2e890 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 rsion 3.6.23.1,
2e8a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 sqlite3_step() b
2e8b0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 egan.** calling
2e8c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2e8d0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 ] automatically
2e8e0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 in this circumst
2e8f0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 ance rather.** t
2e900 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 han returning [S
2e910 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
2e920 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 This is not cons
2e930 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 idered a compati
2e940 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 bility.** break
2e950 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c because any appl
2e960 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 ication that eve
2e970 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 r receives an SQ
2e980 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f LITE_MISUSE erro
2e990 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 r.** is broken b
2e9a0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 y definition. T
2e9b0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f he [SQLITE_OMIT_
2e9c0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 AUTORESET] compi
2e9d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a le-time option.*
2e9e0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f * can be used to
2e9f0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 restore the leg
2ea00 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a acy behavior..**
2ea10 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 .** <b>Goofy Int
2ea20 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 erface Alert:</b
2ea30 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 > In the legacy
2ea40 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 interface, the s
2ea50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a qlite3_step().**
2ea60 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 API always retu
2ea70 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 rns a generic er
2ea80 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 ror code, [SQLIT
2ea90 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 E_ERROR], follow
2eaa0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 ing any.** error
2eab0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
2eac0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 ITE_BUSY] and [S
2ead0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
2eae0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a You must call.**
2eaf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2eb00 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
2eb10 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 inalize()] in or
2eb20 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 der to find one
2eb30 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 of the.** specif
2eb40 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ic [error codes]
2eb50 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 that better des
2eb60 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 cribes the error
2eb70 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 ..** We admit th
2eb80 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f at this is a goo
2eb90 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 fy design. The
2eba0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e problem has been
2ebb0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 fixed.** with t
2ebc0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
2ebd0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 e. If you prepa
2ebe0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 re all of your S
2ebf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
2ec00 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
2ec10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2ec20 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
2ec30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
2ec40 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 instead.** of t
2ec50 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 he legacy [sqlit
2ec60 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e e3_prepare()] an
2ec70 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
2ec80 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 re16()] interfac
2ec90 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 es,.** then the
2eca0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 more specific [e
2ecb0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 rror codes] are
2ecc0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c returned directl
2ecd0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f y.** by sqlite3_
2ece0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 step(). The use
2ecf0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 of the "v2" int
2ed00 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
2ed10 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ended..*/.SQLITE
2ed20 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
2ed30 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
2ed40 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d step(sqlite3_stm
2ed50 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2ed60 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 3REF: Number of
2ed70 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 columns in a res
2ed80 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f ult set.** METHO
2ed90 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
2eda0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2edb0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
2edc0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2edd0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2ede0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a columns in the.
2edf0 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f ** current row o
2ee00 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
2ee10 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 of [prepared st
2ee20 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e atement] P..** ^
2ee30 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 If prepared stat
2ee40 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 ement P does not
2ee50 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 have results re
2ee60 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a ady to return.**
2ee70 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 (via calls to t
2ee80 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
2ee90 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 mn_int | sqlite3
2eea0 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a _column_*()] of.
2eeb0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 ** interfaces) t
2eec0 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 hen sqlite3_data
2eed0 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e _count(P) return
2eee0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s 0..** ^The sql
2eef0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
2ef00 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 P) routine also
2ef10 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 returns 0 if P i
2ef20 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
2ef30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
2ef40 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 3_data_count(P)
2ef50 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
2ef60 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 0 if the previou
2ef70 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 s call to.** [sq
2ef80 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 lite3_step](P) r
2ef90 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
2efa0 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c DONE]. ^The sql
2efb0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
2efc0 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 P).** will retur
2efd0 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 n non-zero if pr
2efe0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b evious call to [
2eff0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 sqlite3_step](P)
2f000 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 returned.** [SQ
2f010 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 LITE_ROW], excep
2f020 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 t in the case of
2f030 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 the [PRAGMA inc
2f040 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d remental_vacuum]
2f050 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 .** where it alw
2f060 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f ays returns zero
2f070 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 since each step
2f080 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 of that multi-s
2f090 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 tep.** pragma re
2f0a0 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 turns 0 columns
2f0b0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 of data..**.** S
2f0c0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
2f0d0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 3_column_count()
2f0e0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
2f0f0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2f100 4c 4c 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f LL sqlite3_data_
2f110 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
2f120 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
2f130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e ** CAPI3REF: Fun
2f140 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 damental Datatyp
2f150 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
2f160 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a SQLITE_TEXT.**.*
2f170 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 * ^(Every value
2f180 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e in SQLite has on
2f190 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d e of five fundam
2f1a0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a ental datatypes:
2f1b0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
2f1c0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 li> 64-bit signe
2f1d0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 d integer.** <li
2f1e0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c > 64-bit IEEE fl
2f1f0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d oating point num
2f200 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 ber.** <li> stri
2f210 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a ng.** <li> BLOB.
2f220 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 ** <li> NULL.**
2f230 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 </ul>)^.**.** Th
2f240 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
2f250 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 e codes for each
2f260 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e of those types.
2f270 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
2f280 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 the SQLITE_TEXT
2f290 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c constant was al
2f2a0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 so used in SQLit
2f2b0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 e version 2.** f
2f2c0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 or a completely
2f2d0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e different meanin
2f2e0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 g. Software tha
2f2f0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 t links against
2f300 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 both.** SQLite v
2f310 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c ersion 2 and SQL
2f320 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 ite version 3 sh
2f330 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 ould use SQLITE3
2f340 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 _TEXT, not.** SQ
2f350 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 LITE_TEXT..*/.#d
2f360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
2f370 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 EGER 1.#define
2f380 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 SQLITE_FLOAT
2f390 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
2f3a0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 _BLOB 4.#def
2f3b0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 ine SQLITE_NULL
2f3c0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 5.#ifdef SQL
2f3d0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 ITE_TEXT.# undef
2f3e0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c SQLITE_TEXT.#el
2f3f0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 se.# define SQLI
2f400 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 TE_TEXT 3.#e
2f410 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c ndif.#define SQL
2f420 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a ITE3_TEXT 3.
2f430 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2f440 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 Result Values F
2f450 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b rom A Query.** K
2f460 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e EYWORDS: {column
2f470 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
2f480 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 s}.** METHOD: sq
2f490 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2f4a0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
2f4b0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 return informat
2f4c0 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 ion about a sing
2f4d0 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 le column of the
2f4e0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 current.** resu
2f4f0 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 lt row of a quer
2f500 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 y. ^In every ca
2f510 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 se the first arg
2f520 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
2f530 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 er.** to the [pr
2f540 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2f550 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 ] that is being
2f560 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b evaluated (the [
2f570 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a sqlite3_stmt*].*
2f580 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 * that was retur
2f590 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
2f5a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2f5b0 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 or one of its va
2f5c0 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 riants).** and t
2f5d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
2f5e0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 nt is the index
2f5f0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f of the column fo
2f600 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 r which informat
2f610 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 ion.** should be
2f620 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 returned. ^The
2f630 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 leftmost column
2f640 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
2f650 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 t has the index
2f660 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 0..** ^The numbe
2f670 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
2f680 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 the result can b
2f690 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 e determined usi
2f6a0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ng.** [sqlite3_c
2f6b0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a olumn_count()]..
2f6c0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c **.** If the SQL
2f6d0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 statement does
2f6e0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f not currently po
2f6f0 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 int to a valid r
2f700 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a ow, or if the.**
2f710 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 column index is
2f720 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 out of range, t
2f730 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 he result is und
2f740 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 efined..** These
2f750 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e routines may on
2f760 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 ly be called whe
2f770 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e n the most recen
2f780 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 t call to.** [sq
2f790 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 lite3_step()] ha
2f7a0 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 s returned [SQLI
2f7b0 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 TE_ROW] and neit
2f7c0 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f her.** [sqlite3_
2f7d0 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 reset()] nor [sq
2f7e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2f7f0 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c ] have been call
2f800 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e ed subsequently.
2f810 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 .** If any of th
2f820 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
2f830 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 called after [s
2f840 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2f850 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 or.** [sqlite3_f
2f860 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 inalize()] or af
2f870 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ter [sqlite3_ste
2f880 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 p()] has returne
2f890 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f d.** something o
2f8a0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
2f8b0 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 E_ROW], the resu
2f8c0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
2f8d0 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 d..** If [sqlite
2f8e0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 3_step()] or [sq
2f8f0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
2f900 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
2f910 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 ize()].** are ca
2f920 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 lled from a diff
2f930 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 erent thread whi
2f940 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 le any of these
2f950 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 routines.** are
2f960 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 pending, then th
2f970 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
2f980 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e defined..**.** ^
2f990 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 The sqlite3_colu
2f9a0 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e mn_type() routin
2f9b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a e returns the.**
2f9c0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
2f9d0 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 | datatype code
2f9e0 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 ] for the initia
2f9f0 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f l data type.** o
2fa00 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c f the result col
2fa10 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 umn. ^The retur
2fa20 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 ned value is one
2fa30 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 of [SQLITE_INTE
2fa40 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 GER],.** [SQLITE
2fa50 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 _FLOAT], [SQLITE
2fa60 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f _TEXT], [SQLITE_
2fa70 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 BLOB], or [SQLIT
2fa80 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 E_NULL]. The va
2fa90 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lue.** returned
2faa0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
2fab0 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 n_type() is only
2fac0 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e meaningful if n
2fad0 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 o type.** conver
2fae0 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 sions have occur
2faf0 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 red as described
2fb00 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 below. After a
2fb10 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
2fb20 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 ,.** the value r
2fb30 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
2fb40 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
2fb50 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 is undefined.
2fb60 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f Future.** versio
2fb70 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 ns of SQLite may
2fb80 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 change the beha
2fb90 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f vior of sqlite3_
2fba0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a column_type().**
2fbb0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 following a typ
2fbc0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a e conversion..**
2fbd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2fbe0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
2fbf0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 UTF-8 string the
2fc00 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f n the sqlite3_co
2fc10 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 lumn_bytes().**
2fc20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
2fc30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
2fc40 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 tes in that BLOB
2fc50 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e or string..** ^
2fc60 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
2fc70 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 a UTF-16 string
2fc80 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
2fc90 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f olumn_bytes() co
2fca0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 nverts.** the st
2fcb0 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e ring to UTF-8 an
2fcc0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 d then returns t
2fcd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
2fce0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 es..** ^If the r
2fcf0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 esult is a numer
2fd00 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 ic value then sq
2fd10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2fd20 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 es() uses.** [sq
2fd30 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
2fd40 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 ] to convert tha
2fd50 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 t value to a UTF
2fd60 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 -8 string and re
2fd70 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d turns.** the num
2fd80 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
2fd90 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 that string..**
2fda0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2fdb0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c s NULL, then sql
2fdc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2fdd0 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f s() returns zero
2fde0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
2fdf0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 result is a BLOB
2fe00 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e or UTF-16 strin
2fe10 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 g then the sqlit
2fe20 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2fe30 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 6().** routine r
2fe40 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
2fe50 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
2fe60 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e at BLOB or strin
2fe70 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 g..** ^If the re
2fe80 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 sult is a UTF-8
2fe90 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c string, then sql
2fea0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2feb0 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a s16() converts.*
2fec0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 * the string to
2fed0 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 UTF-16 and then
2fee0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
2fef0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 er of bytes..**
2ff00 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2ff10 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 s a numeric valu
2ff20 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 e then sqlite3_c
2ff30 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
2ff40 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 uses.** [sqlite3
2ff50 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 _snprintf()] to
2ff60 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c convert that val
2ff70 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 ue to a UTF-16 s
2ff80 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
2ff90 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
2ffa0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2ffb0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
2ffc0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 the result is NU
2ffd0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 LL, then sqlite3
2ffe0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2fff0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a ) returns zero..
30000 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 **.** ^The value
30010 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
30020 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
30030 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b tes()] and .** [
30040 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
30050 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 ytes16()] do not
30060 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 include the zer
30070 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 o terminators at
30080 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 the end.** of t
30090 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 he string. ^For
300a0 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 clarity: the va
300b0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 lues returned by
300c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
300d0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 umn_bytes()] and
300e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
300f0 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 _bytes16()] are
30100 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
30110 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 bytes in the st
30120 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 ring, not the nu
30130 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 mber of characte
30140 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e rs..**.** ^Strin
30150 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 gs returned by s
30160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
30170 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 xt() and sqlite3
30180 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
30190 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 ,.** even empty
301a0 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 strings, are alw
301b0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 ays zero-termina
301c0 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 ted. ^The retur
301d0 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 n.** value from
301e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
301f0 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f lob() for a zero
30200 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 -length BLOB is
30210 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
30220 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 **.** <b>Warning
30230 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 :</b> ^The objec
30240 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 t returned by [s
30250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
30260 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 lue()] is an.**
30270 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
30280 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
30290 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 ct. In a multit
302a0 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d hreaded environm
302b0 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f ent,.** an unpro
302c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
302d0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 alue object may
302e0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61 66 only be used saf
302f0 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c ely with.** [sql
30300 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
30310 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
30320 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e result_value()].
30330 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 .** If the [unpr
30340 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
30350 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 value] object re
30360 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 turned by.** [sq
30370 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
30380 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e ue()] is used in
30390 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 any other way,
303a0 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a including calls.
303b0 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c ** to routines l
303c0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c ike [sqlite3_val
303d0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 ue_int()], [sqli
303e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
303f0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 ],.** or [sqlite
30400 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 3_value_bytes()]
30410 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 , the behavior i
30420 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 s not threadsafe
30430 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
30440 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 utines attempt t
30450 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 o convert the va
30460 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 lue where approp
30470 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 riate. ^For.**
30480 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 example, if the
30490 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
304a0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 ntation is FLOAT
304b0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 and a text resu
304c0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 lt.** is request
304d0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 ed, [sqlite3_snp
304e0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 rintf()] is used
304f0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 internally to p
30500 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f erform the.** co
30510 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 nversion automat
30520 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 ically. ^(The f
30530 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 ollowing table d
30540 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 etails the conve
30550 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 rsions.** that a
30560 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a re applied:.**.*
30570 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a * <blockquote>.*
30580 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
30590 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e "1">.** <tr><th>
305a0 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 Internal<br>Typ
305b0 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 e <th> Requested
305c0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 <br>Type <th> C
305d0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 onversion.**.**
305e0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
305f0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
30600 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
30610 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 0.** <tr><td> N
30620 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f ULL <td> FLO
30630 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c AT <td> Resul
30640 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e t is 0.0.** <tr>
30650 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
30660 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
30670 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 > Result is a NU
30680 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
30690 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
306a0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
306b0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 td> Result is a
306c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
306d0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
306e0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
306f0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 <td> Convert fr
30700 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c om integer to fl
30710 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
30720 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 INTEGER <td>
30730 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
30740 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
30750 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c the integer.** <
30760 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
30770 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
30780 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 <td> Same as INT
30790 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 EGER->TEXT.** <t
307a0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 r><td> FLOAT
307b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
307c0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e td> [CAST] to IN
307d0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 TEGER.** <tr><td
307e0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
307f0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
30800 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
30810 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c f the float.** <
30820 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
30830 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
30840 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 <td> [CAST] to B
30850 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 LOB.** <tr><td>
30860 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e TEXT <td> IN
30870 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 TEGER <td> [CA
30880 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a ST] to INTEGER.*
30890 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
308a0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <td> FLOAT
308b0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 <td> [CAST] t
308c0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 o REAL.** <tr><t
308d0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
308e0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
308f0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 No change.** <tr
30900 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c ><td> BLOB <
30910 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
30920 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 d> [CAST] to INT
30930 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e EGER.** <tr><td>
30940 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 BLOB <td>
30950 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 FLOAT <td> [C
30960 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 AST] to REAL.**
30970 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
30980 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
30990 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f <td> Add a zero
309a0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e terminator if n
309b0 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 eeded.** </table
309c0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 >.** </blockquot
309d0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 e>)^.**.** Note
309e0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 that when type c
309f0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 onversions occur
30a00 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 , pointers retur
30a10 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 ned by prior.**
30a20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
30a30 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 _column_blob(),
30a40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
30a50 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a ext(), and/or.**
30a60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30a70 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 text16() may be
30a80 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 invalidated..**
30a90 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 Type conversions
30aa0 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 and pointer inv
30ab0 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 alidations might
30ac0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 occur.** in the
30ad0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 following cases
30ae0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
30af0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c <li> The initial
30b00 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c content is a BL
30b10 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 OB and sqlite3_c
30b20 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a olumn_text() or.
30b30 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f ** sqlite3_
30b40 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
30b50 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 is called. A ze
30b60 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 ro-terminator mi
30b70 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 ght.** need
30b80 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 to be added to
30b90 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e the string.</li>
30ba0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 .** <li> The ini
30bb0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 tial content is
30bc0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 UTF-8 text and s
30bd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
30be0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 tes16() or.**
30bf0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
30c00 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 n_text16() is ca
30c10 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 lled. The conte
30c20 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 nt must be conve
30c30 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 rted.** to
30c40 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 UTF-16.</li>.**
30c50 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c <li> The initial
30c60 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d content is UTF-
30c70 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 16 text and sqli
30c80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
30c90 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
30ca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
30cb0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 t() is called.
30cc0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 The content must
30cd0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a be converted.**
30ce0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c to UTF-8.<
30cf0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a /li>.** </ul>.**
30d00 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 .** ^Conversions
30d10 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 between UTF-16b
30d20 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 e and UTF-16le a
30d30 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 re always done i
30d40 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a n place and do.*
30d50 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 * not invalidate
30d60 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 a prior pointer
30d70 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 , though of cour
30d80 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f se the content o
30d90 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 f the buffer.**
30da0 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 that the prior p
30db0 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 ointer reference
30dc0 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e s will have been
30dd0 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 modified. Othe
30de0 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f r kinds.** of co
30df0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e nversion are don
30e00 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 e in place when
30e10 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 it is possible,
30e20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 but sometimes th
30e30 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f ey.** are not po
30e40 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 ssible and in th
30e50 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 ose cases prior
30e60 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 pointers are inv
30e70 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 alidated..**.**
30e80 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 The safest polic
30e90 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 y is to invoke t
30ea0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a hese routines.**
30eb0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 in one of the f
30ec0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a ollowing ways:.*
30ed0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c *.** <ul>.** <l
30ee0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e i>sqlite3_column
30ef0 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 _text() followed
30f00 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
30f10 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a mn_bytes()</li>.
30f20 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f ** <li>sqlite3_
30f30 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f column_blob() fo
30f40 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
30f50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
30f60 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 </li>.** <li>sq
30f70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
30f80 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 t16() followed b
30f90 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
30fa0 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a _bytes16()</li>.
30fb0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </ul>.**.** I
30fc0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 n other words, y
30fd0 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 ou should call s
30fe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
30ff0 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 xt(),.** sqlite3
31000 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 _column_blob(),
31010 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
31020 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 n_text16() first
31030 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 to force the re
31040 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 sult.** into the
31050 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c desired format,
31060 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c then invoke sql
31070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
31080 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 s() or.** sqlite
31090 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
310a0 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 () to find the s
310b0 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ize of the resul
310c0 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 t. Do not mix c
310d0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 alls.** to sqlit
310e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
310f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
31100 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 mn_blob() with c
31110 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 alls to.** sqlit
31120 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
31130 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6(), and do not
31140 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c mix calls to sql
31150 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
31160 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 16().** with cal
31170 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
31180 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a lumn_bytes()..**
31190 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 .** ^The pointer
311a0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 s returned are v
311b0 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 alid until a typ
311c0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 e conversion occ
311d0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 urs as.** descri
311e0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e bed above, or un
311f0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 til [sqlite3_ste
31200 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 p()] or [sqlite3
31210 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 _reset()] or.**
31220 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
31230 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 e()] is called.
31240 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 ^The memory spa
31250 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 ce used to hold
31260 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 strings.** and B
31270 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 LOBs is freed au
31280 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f tomatically. Do
31290 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 <em>not</em> pa
312a0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 ss the pointers
312b0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d returned.** from
312c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
312d0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 _blob()], [sqlit
312e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
312f0 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 ], etc. into.**
31300 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
31310 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d ..**.** ^(If a m
31320 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
31330 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 error occurs du
31340 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 ring the evaluat
31350 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 ion of any.** of
31360 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c these routines,
31370 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 a default value
31380 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 is returned. T
31390 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 he default value
313a0 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 .** is either th
313b0 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 e integer 0, the
313c0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
313d0 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 number 0.0, or a
313e0 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 NULL.** pointer
313f0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 . Subsequent ca
31400 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
31410 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 errcode()] will
31420 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 return.** [SQLIT
31430 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 E_NOMEM].)^.*/.S
31440 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
31450 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 void *SQLITE_STD
31460 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
31470 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 umn_blob(sqlite3
31480 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
31490 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
314a0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
314b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
314c0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 bytes(sqlite3_st
314d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
314e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
314f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
31500 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
31510 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d es16(sqlite3_stm
31520 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
31530 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 QLITE_API double
31540 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
31550 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
31560 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 ouble(sqlite3_st
31570 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
31580 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
31590 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
315a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
315b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
315c0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
315d0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e E_API sqlite3_in
315e0 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 t64 SQLITE_STDCA
315f0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
31600 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f n_int64(sqlite3_
31610 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
31620 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
31630 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 st unsigned char
31640 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
31650 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
31660 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d text(sqlite3_stm
31670 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
31680 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
31690 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 void *SQLITE_STD
316a0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
316b0 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 umn_text16(sqlit
316c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
316d0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
316e0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
316f0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
31700 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 n_type(sqlite3_s
31710 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
31720 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
31730 74 65 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54 te3_value *SQLIT
31740 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
31750 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 3_column_value(s
31760 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
31770 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t iCol);../*.**
31780 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f CAPI3REF: Destro
31790 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 y A Prepared Sta
317a0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a tement Object.**
317b0 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c DESTRUCTOR: sql
317c0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
317d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e ^The sqlite3_fin
317e0 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e alize() function
317f0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 is called to de
31800 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 lete a [prepared
31810 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
31820 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
31830 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f ent evaluation o
31840 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
31850 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 encountered no e
31860 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 rrors.** or if t
31870 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
31880 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 never been evalu
31890 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 ated, then sqlit
318a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 e3_finalize() re
318b0 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f turns.** SQLITE_
318c0 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 OK. ^If the mos
318d0 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 t recent evaluat
318e0 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 ion of statement
318f0 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a S failed, then.
31900 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c ** sqlite3_final
31910 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 ize(S) returns t
31920 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b he appropriate [
31930 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a error code] or.*
31940 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f * [extended erro
31950 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e r code]..**.** ^
31960 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 The sqlite3_fina
31970 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 lize(S) routine
31980 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 can be called at
31990 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e any point durin
319a0 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 g.** the life cy
319b0 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 cle of [prepared
319c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a statement] S:.*
319d0 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 * before stateme
319e0 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 nt S is ever eva
319f0 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a luated, after.**
31a00 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c one or more cal
31a10 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ls to [sqlite3_r
31a20 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 eset()], or afte
31a30 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f r any call.** to
31a40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
31a50 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 ] regardless of
31a60 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
31a70 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 he statement has
31a80 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 .** completed ex
31a90 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e ecution..**.** ^
31aa0 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 Invoking sqlite3
31ab0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 _finalize() on a
31ac0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
31ad0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f a harmless no-o
31ae0 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 p..**.** The app
31af0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 lication must fi
31b00 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 nalize every [pr
31b10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
31b20 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 ] in order to av
31b30 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 oid.** resource
31b40 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 leaks. It is a
31b50 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 grievous error f
31b60 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 or the applicati
31b70 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 on to try to use
31b80 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 .** a prepared s
31b90 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 tatement after i
31ba0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c t has been final
31bb0 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f ized. Any use o
31bc0 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 f a prepared.**
31bd0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 statement after
31be0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 it has been fina
31bf0 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 lized can result
31c00 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e in undefined an
31c10 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 d.** undesirable
31c20 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 behavior such a
31c30 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 s segfaults and
31c40 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e heap corruption.
31c50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
31c60 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
31c70 4c 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 L sqlite3_finali
31c80 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ze(sqlite3_stmt
31c90 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
31ca0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 CAPI3REF: Reset
31cb0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
31cc0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d ment Object.** M
31cd0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
31ce0 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 tmt.**.** The sq
31cf0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 lite3_reset() fu
31d00 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 nction is called
31d10 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 to reset a [pre
31d20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
31d30 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 .** object back
31d40 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 to its initial s
31d50 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 tate, ready to b
31d60 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a e re-executed..*
31d70 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 * ^Any SQL state
31d80 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 ment variables t
31d90 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 hat had values b
31da0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 ound to them usi
31db0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 ng.** the [sqlit
31dc0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 e3_bind_blob | s
31dd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
31de0 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 API] retain thei
31df0 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 r values..** Use
31e00 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f [sqlite3_clear_
31e10 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 bindings()] to r
31e20 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 eset the binding
31e30 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 s..**.** ^The [s
31e40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
31e50 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 interface reset
31e60 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 s the [prepared
31e70 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 statement] S.**
31e80 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 back to the begi
31e90 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f nning of its pro
31ea0 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 gram..**.** ^If
31eb0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
31ec0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
31ed0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 _step(S)] for th
31ee0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
31ef0 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 tatement] S retu
31f00 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 rned [SQLITE_ROW
31f10 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e ] or [SQLITE_DON
31f20 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 E],.** or if [sq
31f30 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 lite3_step(S)] h
31f40 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 as never before
31f50 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 been called on S
31f60 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 ,.** then [sqlit
31f70 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 e3_reset(S)] ret
31f80 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
31f90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
31fa0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c most recent call
31fb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
31fc0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a p(S)] for the.**
31fd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
31fe0 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 ment] S indicate
31ff0 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e d an error, then
32000 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
32010 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 et(S)] returns a
32020 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 n appropriate [e
32030 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a rror code]..**.*
32040 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
32050 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 reset(S)] interf
32060 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 ace does not cha
32070 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a nge the values.*
32080 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 * of any [sqlite
32090 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 3_bind_blob|bind
320a0 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 ings] on the [pr
320b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
320c0 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ] S..*/.SQLITE_A
320d0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
320e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 DCALL sqlite3_re
320f0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 set(sqlite3_stmt
32100 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
32110 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 CAPI3REF: Creat
32120 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 e Or Redefine SQ
32130 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b L Functions.** K
32140 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 EYWORDS: {functi
32150 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
32160 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 ines}.** KEYWORD
32170 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
32180 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
32190 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 tion}.** KEYWORD
321a0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
321b0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
321c0 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 tions}.** METHOD
321d0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
321e0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
321f0 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b (collectively k
32200 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f nown as "functio
32210 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 n creation routi
32220 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 nes").** are use
32230 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e d to add SQL fun
32240 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
32250 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 ates or to redef
32260 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 ine the behavior
32270 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 .** of existing
32280 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 SQL functions or
32290 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 aggregates. Th
322a0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 e only differenc
322b0 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 es between.** th
322c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
322d0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 the text encodi
322e0 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a ng expected for.
322f0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 ** the second pa
32300 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d rameter (the nam
32310 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f e of the functio
32320 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 n being created)
32330 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 .** and the pres
32340 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 ence or absence
32350 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 of a destructor
32360 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 callback for.**
32370 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
32380 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a data pointer..**
32390 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 .** ^The first p
323a0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
323b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
323c0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 tion] to which t
323d0 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 he SQL.** functi
323e0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 on is to be adde
323f0 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 d. ^If an appli
32400 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 cation uses more
32410 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 than one databa
32420 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
32430 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f then applicatio
32440 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
32450 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 nctions must be
32460 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 added.** to each
32470 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
32480 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e tion separately.
32490 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f .**.** ^The seco
324a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
324b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
324c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
324d0 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a be created or.**
324e0 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 redefined. ^Th
324f0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
32500 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 name is limited
32510 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 to 255 bytes in
32520 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 a UTF-8.** repre
32530 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 sentation, exclu
32540 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f sive of the zero
32550 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e -terminator. ^N
32560 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d ote that the nam
32570 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 e.** length limi
32580 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 t is in UTF-8 by
32590 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 tes, not charact
325a0 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 ers nor UTF-16 b
325b0 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 ytes. .** ^Any
325c0 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 attempt to creat
325d0 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 e a function wit
325e0 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a h a longer name.
325f0 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 ** will result i
32600 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 n [SQLITE_MISUSE
32610 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 ] being returned
32620 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 ..**.** ^The thi
32630 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 rd parameter (nA
32640 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 rg).** is the nu
32650 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
32660 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 s that the SQL f
32670 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
32680 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e gregate takes. ^
32690 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 If this paramete
326a0 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 r is -1, then th
326b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
326c0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d r.** aggregate m
326d0 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 ay take any numb
326e0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
326f0 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 between 0 and th
32700 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 e limit.** set b
32710 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 y [sqlite3_limit
32720 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ]([SQLITE_LIMIT_
32730 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 FUNCTION_ARG]).
32740 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a If the third.**
32750 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 parameter is le
32760 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 ss than -1 or gr
32770 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 eater than 127 t
32780 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
32790 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 is.** undefined
327a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
327b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 rth parameter, e
327c0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 TextRep, specifi
327d0 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 es what.** [SQLI
327e0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 TE_UTF8 | text e
327f0 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 ncoding] this SQ
32800 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 L function prefe
32810 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 rs for.** its pa
32820 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 rameters. The a
32830 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
32840 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d d set this param
32850 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 eter to.** [SQLI
32860 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 TE_UTF16LE] if t
32870 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c he function impl
32880 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b ementation invok
32890 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f es .** [sqlite3_
328a0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 value_text16le()
328b0 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f ] on an input, o
328c0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 r [SQLITE_UTF16B
328d0 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 E] if the.** imp
328e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f lementation invo
328f0 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c kes [sqlite3_val
32900 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f ue_text16be()] o
32910 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a n an input, or.*
32920 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d * [SQLITE_UTF16]
32930 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c if [sqlite3_val
32940 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 ue_text16()] is
32950 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 used, or [SQLITE
32960 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 _UTF8].** otherw
32970 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 ise. ^The same
32980 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 SQL function may
32990 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d be registered m
329a0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 ultiple times us
329b0 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 ing.** different
329c0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
329d0 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 encodings, with
329e0 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d different implem
329f0 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a entations for.**
32a00 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a each encoding..
32a10 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c ** ^When multipl
32a20 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
32a30 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
32a40 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c nction are avail
32a50 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 able, SQLite.**
32a60 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e will pick the on
32a70 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 e that involves
32a80 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 the least amount
32a90 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 of data convers
32aa0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ion..**.** ^The
32ab0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
32ac0 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 may optionally
32ad0 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 be ORed with [SQ
32ae0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 LITE_DETERMINIST
32af0 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c IC].** to signal
32b00 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 that the functi
32b10 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 on will always r
32b20 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 eturn the same r
32b30 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 esult given.** t
32b40 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 he same inputs w
32b50 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 ithin a single S
32b60 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d QL statement. M
32b70 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ost SQL function
32b80 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 s are.** determi
32b90 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 nistic. The bui
32ba0 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d lt-in [random()]
32bb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 SQL function is
32bc0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 an example of a
32bd0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 .** function tha
32be0 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 t is not determi
32bf0 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c nistic. The SQL
32c00 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 ite query planne
32c10 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 r is able to.**
32c20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e perform addition
32c30 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 al optimizations
32c40 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 on deterministi
32c50 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 c functions, so
32c60 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 use.** of the [S
32c70 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 QLITE_DETERMINIS
32c80 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 TIC] flag is rec
32c90 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 ommended where p
32ca0 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e ossible..**.** ^
32cb0 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d (The fifth param
32cc0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 eter is an arbit
32cd0 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 rary pointer. T
32ce0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
32cf0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 n of the.** func
32d00 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 tion can gain ac
32d10 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 cess to this poi
32d20 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 nter using [sqli
32d30 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d te3_user_data()]
32d40 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
32d50 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e ixth, seventh an
32d60 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 d eighth paramet
32d70 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 ers, xFunc, xSte
32d80 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 p and xFinal, ar
32d90 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f e.** pointers to
32da0 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 C-language func
32db0 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 tions that imple
32dc0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e ment the SQL fun
32dd0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
32de0 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 egate. ^A scalar
32df0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 SQL function re
32e00 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d quires an implem
32e10 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 entation of the
32e20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 xFunc.** callbac
32e30 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 k only; NULL poi
32e40 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 nters must be pa
32e50 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 ssed as the xSte
32e60 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 p and xFinal.**
32e70 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 parameters. ^An
32e80 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
32e90 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
32ea0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f an implementatio
32eb0 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e n of xStep.** an
32ec0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c d xFinal and NUL
32ed0 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 L pointer must b
32ee0 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 e passed for xFu
32ef0 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 nc. ^To delete a
32f00 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 n existing.** SQ
32f10 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 L function or ag
32f20 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 gregate, pass NU
32f30 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 LL pointers for
32f40 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 all three functi
32f50 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e on.** callbacks.
32f60 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 .**.** ^(If the
32f70 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 ninth parameter
32f80 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 to sqlite3_creat
32f90 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 e_function_v2()
32fa0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 is not NULL,.**
32fb0 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 then it is destr
32fc0 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 uctor for the ap
32fd0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 plication data p
32fe0 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 ointer. .** The
32ff0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e destructor is in
33000 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 voked when the f
33010 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 unction is delet
33020 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 ed, either by be
33030 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 ing.** overloade
33040 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 d or when the da
33050 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
33060 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e n closes.)^.** ^
33070 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
33080 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 s also invoked i
33090 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a f the call to.**
330a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
330b0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 function_v2() fa
330c0 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 ils..** ^When th
330d0 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c e destructor cal
330e0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e lback of the ten
330f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
33100 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 invoked, it.** i
33110 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c s passed a singl
33120 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
33130 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
33140 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 e application da
33150 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 ta .** pointer w
33160 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 hich was the fif
33170 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
33180 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
33190 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a unction_v2()..**
331a0 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 .** ^It is permi
331b0 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 tted to register
331c0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d multiple implem
331d0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 entations of the
331e0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f same.** functio
331f0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 ns with the same
33200 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 name but with e
33210 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 ither differing
33220 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 numbers of.** ar
33230 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 guments or diffe
33240 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 ring preferred t
33250 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 ext encodings.
33260 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 ^SQLite will use
33270 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
33280 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 tation that most
33290 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 closely matches
332a0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 the way in whic
332b0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e h the.** SQL fun
332c0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 ction is used.
332d0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c ^A function impl
332e0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 ementation with
332f0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a a non-negative.*
33300 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 * nArg parameter
33310 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 is a better mat
33320 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 ch than a functi
33330 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
33340 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 n with.** a nega
33350 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 tive nArg. ^A f
33360 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
33370 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 e preferred text
33380 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 encoding.** mat
33390 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 ches the databas
333a0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 e encoding is a
333b0 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 better.** match
333c0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
333d0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
333e0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e ng is different.
333f0 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f .** ^A functio
33400 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
33410 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 ding difference
33420 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 is between UTF16
33430 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a le and UTF16be.*
33440 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 * is a closer ma
33450 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 tch than a funct
33460 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e ion where the en
33470 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 coding differenc
33480 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 e is.** between
33490 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a UTF8 and UTF16..
334a0 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 **.** ^Built-in
334b0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 functions may be
334c0 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e overloaded by n
334d0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 ew application-d
334e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 efined functions
334f0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c ..**.** ^An appl
33500 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
33510 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d function is perm
33520 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 itted to call ot
33530 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e her.** SQLite in
33540 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 terfaces. Howev
33550 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d er, such calls m
33560 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 ust not.** close
33570 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
33580 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e nnection nor fin
33590 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 alize or reset t
335a0 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 he prepared.** s
335b0 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 tatement in whic
335c0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 h the function i
335d0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 s running..*/.SQ
335e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
335f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
33600 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
33610 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ion(. sqlite3 *
33620 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 db,. const char
33630 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c *zFunctionName,
33640 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 . int nArg,. i
33650 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 nt eTextRep,. v
33660 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 oid *pApp,. voi
33670 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 d (*xFunc)(sqlit
33680 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
33690 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
336a0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 ,. void (*xStep
336b0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
336c0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
336d0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
336e0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 (*xFinal)(sqlite
336f0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 3_context*).);.S
33700 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
33710 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
33720 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
33730 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 tion16(. sqlite
33740 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 3 *db,. const v
33750 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 oid *zFunctionNa
33760 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
33770 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
33780 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
33790 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
337a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
337b0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
337c0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
337d0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
337e0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
337f0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
33800 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
33810 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 ite3_context*).)
33820 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
33830 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
33840 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
33850 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 unction_v2(. sq
33860 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e lite3 *db,. con
33870 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 st char *zFuncti
33880 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 onName,. int nA
33890 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 rg,. int eTextR
338a0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 ep,. void *pApp
338b0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 ,. void (*xFunc
338c0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
338d0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
338e0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
338f0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 (*xStep)(sqlite3
33900 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
33910 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
33920 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 void (*xFinal)
33930 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
33940 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 *),. void(*xDes
33950 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a troy)(void*).);.
33960 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
33970 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a Text Encodings.
33980 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
33990 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 tant define inte
339a0 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 ger codes that r
339b0 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 epresent the var
339c0 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 ious.** text enc
339d0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 odings supported
339e0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 by SQLite..*/.#
339f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
33a00 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20 F8 1
33a10 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 /* IMP: R-3751
33a20 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 4-35566 */.#defi
33a30 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c ne SQLITE_UTF16L
33a40 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a E 2 /*
33a50 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 IMP: R-03371-37
33a60 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 637 */.#define S
33a70 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 QLITE_UTF16BE
33a80 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3 /* IMP
33a90 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 : R-51971-34154
33aa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
33ab0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 E_UTF16
33ac0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 4 /* Use nat
33ad0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a ive byte order *
33ae0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
33af0 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 _ANY
33b00 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 5 /* Deprecat
33b10 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
33b20 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e LITE_UTF16_ALIGN
33b30 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 ED 8 /* sqli
33b40 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
33b50 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a tion only */../*
33b60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 .** CAPI3REF: Fu
33b70 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a nction Flags.**.
33b80 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
33b90 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 ts may be ORed t
33ba0 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65 ogether with the
33bb0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 .** [SQLITE_UTF
33bc0 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 8 | preferred te
33bd0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 xt encoding] as
33be0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d the fourth argum
33bf0 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 ent.** to [sqlit
33c00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
33c10 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f on()], [sqlite3_
33c20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
33c30 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 6()], or.** [sql
33c40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
33c50 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 tion_v2()]..*/.#
33c60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
33c70 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 TERMINISTIC 0
33c80 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 x800../*.** CAPI
33c90 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 3REF: Deprecated
33ca0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 Functions.** DE
33cb0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 PRECATED.**.** T
33cc0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 hese functions a
33cd0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e re [deprecated].
33ce0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 In order to ma
33cf0 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 intain.** backwa
33d00 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
33d10 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 y with older cod
33d20 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f e, these functio
33d30 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 ns continue .**
33d40 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e to be supported.
33d50 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 However, new a
33d60 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
33d70 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 ld avoid.** the
33d80 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e use of these fun
33d90 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f ctions. To enco
33da0 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 urage programmer
33db0 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 s to avoid.** th
33dc0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 ese functions, w
33dd0 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 e will not expla
33de0 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e in what they do.
33df0 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 .*/.#ifndef SQLI
33e00 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 TE_OMIT_DEPRECAT
33e10 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 ED.SQLITE_API SQ
33e20 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
33e30 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
33e40 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 LL sqlite3_aggre
33e50 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 gate_count(sqlit
33e60 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 e3_context*);.SQ
33e70 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
33e80 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 DEPRECATED int S
33e90 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
33ea0 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 lite3_expired(sq
33eb0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 lite3_stmt*);.SQ
33ec0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
33ed0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 DEPRECATED int S
33ee0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
33ef0 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 lite3_transfer_b
33f00 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f indings(sqlite3_
33f10 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 stmt*, sqlite3_s
33f20 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 tmt*);.SQLITE_AP
33f30 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 I SQLITE_DEPRECA
33f40 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 TED int SQLITE_S
33f50 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 TDCALL sqlite3_g
33f60 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f lobal_recover(vo
33f70 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 id);.SQLITE_API
33f80 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
33f90 44 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 D void SQLITE_ST
33fa0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 68 DCALL sqlite3_th
33fb0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 read_cleanup(voi
33fc0 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 d);.SQLITE_API S
33fd0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
33fe0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
33ff0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ALL sqlite3_memo
34000 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 ry_alarm(void(*)
34010 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 (void*,sqlite3_i
34020 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 nt64,int),.
34030 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
34040 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 void*,sqlite3_i
34050 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f nt64);.#endif../
34060 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
34070 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c btaining SQL Val
34080 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ues.** METHOD: s
34090 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a qlite3_value.**.
340a0 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 ** The C-languag
340b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
340c0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e of SQL function
340d0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 s and aggregates
340e0 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 uses.** this se
340f0 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 t of interface r
34100 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 outines to acces
34110 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 s the parameter
34120 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 values on.** the
34130 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 function or agg
34140 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 regate. .**.**
34150 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 The xFunc (for s
34160 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 calar functions)
34170 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 or xStep (for a
34180 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d ggregates) param
34190 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c eters.** to [sql
341a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
341b0 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c tion()] and [sql
341c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
341d0 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 tion16()].** def
341e0 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 ine callbacks th
341f0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 at implement the
34200 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 SQL functions a
34210 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a nd aggregates..*
34220 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 * The 3rd parame
34230 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c ter to these cal
34240 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 lbacks is an arr
34250 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
34260 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 o.** [protected
34270 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
34280 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 bjects. There i
34290 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 s one [sqlite3_v
342a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 alue] object for
342b0 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 .** each paramet
342c0 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 er to the SQL fu
342d0 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 nction. These r
342e0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 outines are used
342f0 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 to.** extract v
34300 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b alues from the [
34310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
34320 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 bjects..**.** Th
34330 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 ese routines wor
34340 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f k only with [pro
34350 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
34360 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a alue] objects..*
34370 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f * Any attempt to
34380 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 use these routi
34390 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f nes on an [unpro
343a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
343b0 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 alue].** object
343c0 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 results in undef
343d0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a ined behavior..*
343e0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
343f0 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c ines work just l
34400 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f ike the correspo
34410 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 nding [column ac
34420 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a cess functions].
34430 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 74 ** except that t
34440 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 hese routines ta
34450 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f ke a single [pro
34460 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
34470 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 alue] object.**
34480 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 pointer instead
34490 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 of a [sqlite3_st
344a0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 mt*] pointer and
344b0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 an integer colu
344c0 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a mn number..**.**
344d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^The sqlite3_va
344e0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 lue_text16() int
344f0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 erface extracts
34500 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a a UTF-16 string.
34510 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 ** in the native
34520 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 byte-order of t
34530 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e he host machine.
34540 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 ^The.** sqlite
34550 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
34560 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 () and sqlite3_v
34570 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 alue_text16le()
34580 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 interfaces.** ex
34590 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 tract UTF-16 str
345a0 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 ings as big-endi
345b0 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e an and little-en
345c0 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c dian respectivel
345d0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 y..**.** ^(The s
345e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d qlite3_value_num
345f0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 eric_type() inte
34600 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
34610 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 o apply.** numer
34620 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 ic affinity to t
34630 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 he value. This
34640 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 means that an at
34650 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 tempt is.** made
34660 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
34670 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 value to an inte
34680 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 ger or floating
34690 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 point. If.** su
346a0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ch a conversion
346b0 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 is possible with
346c0 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f out loss of info
346d0 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 rmation (in othe
346e0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 r.** words, if t
346f0 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 he value is a st
34700 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 ring that looks
34710 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a like a number).*
34720 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 * then the conve
34730 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d rsion is perform
34740 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e ed. Otherwise n
34750 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 o conversion occ
34760 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c urs..** The [SQL
34770 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 ITE_INTEGER | da
34780 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f tatype] after co
34790 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 nversion is retu
347a0 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c rned.)^.**.** Pl
347b0 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 ease pay particu
347c0 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f lar attention to
347d0 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 the fact that t
347e0 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 he pointer retur
347f0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
34800 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
34810 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
34820 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a ue_text()], or.*
34830 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 * [sqlite3_value
34840 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 _text16()] can b
34850 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 e invalidated by
34860 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 a subsequent ca
34870 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
34880 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 3_value_bytes()]
34890 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
348a0 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 _bytes16()], [sq
348b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
348c0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 ()],.** or [sqli
348d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
348e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ()]..**.** These
348f0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 routines must b
34900 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
34910 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 e same thread as
34920 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 .** the SQL func
34930 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 tion that suppli
34940 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ed the [sqlite3_
34950 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 value*] paramete
34960 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 rs..*/.SQLITE_AP
34970 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 I const void *SQ
34980 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
34990 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
349a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
349b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
349c0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
349d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
349e0 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 es(sqlite3_value
349f0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
34a00 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
34a10 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f L sqlite3_value_
34a20 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f bytes16(sqlite3_
34a30 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
34a40 41 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 API double SQLIT
34a50 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
34a60 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 3_value_double(s
34a70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
34a80 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
34a90 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
34aa0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 lite3_value_int(
34ab0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
34ac0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
34ad0 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 te3_int64 SQLITE
34ae0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
34af0 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c _value_int64(sql
34b00 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
34b10 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 LITE_API const u
34b20 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51 nsigned char *SQ
34b30 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
34b40 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
34b50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
34b60 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
34b70 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 t void *SQLITE_S
34b80 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
34b90 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 alue_text16(sqli
34ba0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
34bb0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
34bc0 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 id *SQLITE_STDCA
34bd0 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 LL sqlite3_value
34be0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
34bf0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
34c00 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
34c10 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
34c20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
34c30 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f ext16be(sqlite3_
34c40 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
34c50 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
34c60 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
34c70 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 alue_type(sqlite
34c80 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
34c90 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
34ca0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
34cb0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
34cc0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
34cd0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 e*);../*.** CAPI
34ce0 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 3REF: Copy And F
34cf0 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a ree SQL Values.*
34d00 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
34d10 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 3_value.**.** ^T
34d20 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
34d30 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 _dup(V) interfac
34d40 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
34d50 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 f the [sqlite3_v
34d60 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 alue].** object
34d70 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 D and returns a
34d80 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 pointer to that
34d90 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c copy. ^The [sql
34da0 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 ite3_value] retu
34db0 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 rned.** is a [pr
34dc0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
34dd0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 value] object ev
34de0 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 en if the input
34df0 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 is not..** ^The
34e00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 sqlite3_value_du
34e10 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 72 p(V) interface r
34e20 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 eturns NULL if V
34e30 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 is NULL or if a
34e40 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
34e50 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a ation fails..**.
34e60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
34e70 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 6e value_free(V) in
34e80 74 65 72 66 61 63 65 20 66 72 65 65 73 20 61 6e terface frees an
34e90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
34ea0 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 object.** previ
34eb0 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 ously obtained f
34ec0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c rom [sqlite3_val
34ed0 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 ue_dup()]. ^If
34ee0 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e V is a NULL poin
34ef0 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 ter.** then sqli
34f00 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 te3_value_free(V
34f10 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 ) is a harmless
34f20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 no-op..*/.SQLITE
34f30 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 _API SQLITE_EXPE
34f40 52 49 4d 45 4e 54 41 4c 20 73 71 6c 69 74 65 33 RIMENTAL sqlite3
34f50 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 _value *SQLITE_S
34f60 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
34f70 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 alue_dup(const s
34f80 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
34f90 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
34fa0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 E_EXPERIMENTAL v
34fb0 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 oid SQLITE_STDCA
34fc0 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 LL sqlite3_value
34fd0 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 _free(sqlite3_va
34fe0 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lue*);../*.** CA
34ff0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 PI3REF: Obtain A
35000 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f ggregate Functio
35010 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 n Context.** MET
35020 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e HOD: sqlite3_con
35030 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 text.**.** Imple
35040 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 mentations of ag
35050 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
35060 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a tions use this.*
35070 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c * routine to all
35080 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 ocate memory for
35090 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 storing their s
350a0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tate..**.** ^The
350b0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 first time the
350c0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
350d0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 e_context(C,N) r
350e0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 outine is called
350f0 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 .** for a parti
35100 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 cular aggregate
35110 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 function, SQLite
35120 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 .** allocates N
35130 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 of memory, zeroe
35140 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 s out that memor
35150 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 y, and returns a
35160 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 pointer.** to t
35170 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e he new memory. ^
35180 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 On second and su
35190 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
351a0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 o.** sqlite3_agg
351b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
351c0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 for the same ag
351d0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
351e0 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 instance,.** th
351f0 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 e same buffer is
35200 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 returned. Sqli
35210 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
35220 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 ntext() is norma
35230 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e lly.** called on
35240 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f ce for each invo
35250 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 cation of the xS
35260 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 tep callback and
35270 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 then one.** las
35280 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 t time when the
35290 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 xFinal callback
352a0 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 is invoked. ^(W
352b0 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 hen no rows matc
352c0 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 h.** an aggregat
352d0 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 e query, the xSt
352e0 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 ep() callback of
352f0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 the aggregate f
35300 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 unction.** imple
35310 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 mentation is nev
35320 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 er called and xF
35330 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 inal() is called
35340 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a exactly once..*
35350 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 * In those cases
35360 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 , sqlite3_aggreg
35370 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 ate_context() mi
35380 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f ght be called fo
35390 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 r the.** first t
353a0 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 ime from within
353b0 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a xFinal().)^.**.*
353c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 * ^The sqlite3_a
353d0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
353e0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 (C,N) routine re
353f0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
35400 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 nter .** when fi
35410 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 rst called if N
35420 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 is less than or
35430 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 equal to zero or
35440 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 if a memory.**
35450 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f allocate error o
35460 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 ccurs..**.** ^(T
35470 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 he amount of spa
35480 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 ce allocated by
35490 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
354a0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 e_context(C,N) i
354b0 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 s.** determined
354c0 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 by the N paramet
354d0 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 er on first succ
354e0 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 essful call. Ch
354f0 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 anging the.** va
35500 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 lue of N in subs
35510 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 equent call to s
35520 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
35530 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 _context() withi
35540 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 n.** the same ag
35550 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
35560 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e instance will n
35570 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 ot resize the me
35580 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 mory.** allocati
35590 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 on.)^ Within th
355a0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 e xFinal callbac
355b0 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 k, it is customa
355c0 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 ry to set.** N=0
355d0 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c in calls to sql
355e0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
355f0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 ontext(C,N) so t
35600 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 hat no .** point
35610 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f less memory allo
35620 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a cations occur..*
35630 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 *.** ^SQLite aut
35640 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 omatically frees
35650 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
35660 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c cated by .** sql
35670 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
35680 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 ontext() when th
35690 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 e aggregate quer
356a0 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a y concludes..**.
356b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 ** The first par
356c0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 ameter must be a
356d0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
356e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 [sqlite3_context
356f0 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 | SQL function
35700 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 context] that is
35710 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
35720 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 eter.** to the x
35730 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 Step or xFinal c
35740 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 allback routine
35750 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 that implements
35760 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a the aggregate.**
35770 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
35780 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 This routine mu
35790 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f st be called fro
357a0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 m the same threa
357b0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 d in which.** th
357c0 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 e aggregate SQL
357d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
357e0 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ing..*/.SQLITE_A
357f0 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f PI void *SQLITE_
35800 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
35810 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
35820 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
35830 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b t*, int nBytes);
35840 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
35850 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 : User Data For
35860 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 Functions.** MET
35870 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e HOD: sqlite3_con
35880 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 text.**.** ^The
35890 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
358a0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 a() interface re
358b0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a turns a copy of.
358c0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 ** the pointer t
358d0 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 hat was the pUse
358e0 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 rData parameter
358f0 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 (the 5th paramet
35900 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 er).** of the [s
35910 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
35920 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 nction()].** and
35930 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
35940 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 _function16()] r
35950 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 outines that ori
35960 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 ginally.** regis
35970 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 tered the applic
35980 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 ation defined fu
35990 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 nction..**.** Th
359a0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 is routine must
359b0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
359c0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
359d0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 n which.** the a
359e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
359f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ed function is r
35a00 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 unning..*/.SQLIT
35a10 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 E_API void *SQLI
35a20 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
35a30 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c e3_user_data(sql
35a40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
35a50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
35a60 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
35a70 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f tion For Functio
35a80 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ns.** METHOD: sq
35a90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a lite3_context.**
35aa0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
35ab0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 _context_db_hand
35ac0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 le() interface r
35ad0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 eturns a copy of
35ae0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 .** the pointer
35af0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 to the [database
35b00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 connection] (th
35b10 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 e 1st parameter)
35b20 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
35b30 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
35b40 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ion()].** and [s
35b50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
35b60 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 nction16()] rout
35b70 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e ines that origin
35b80 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 ally.** register
35b90 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ed the applicati
35ba0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on defined funct
35bb0 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ion..*/.SQLITE_A
35bc0 50 49 20 73 71 6c 69 74 65 33 20 2a 53 51 4c 49 PI sqlite3 *SQLI
35bd0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
35be0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 e3_context_db_ha
35bf0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e ndle(sqlite3_con
35c00 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 text*);../*.** C
35c10 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f API3REF: Functio
35c20 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 n Auxiliary Data
35c30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
35c40 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a te3_context.**.*
35c50 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
35c60 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 s may be used by
35c70 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 (non-aggregate)
35c80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 SQL functions t
35c90 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d o.** associate m
35ca0 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 etadata with arg
35cb0 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 ument values. If
35cc0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 the same value
35cd0 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 is passed to.**
35ce0 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 multiple invocat
35cf0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
35d00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 SQL function du
35d10 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 ring query execu
35d20 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 tion, under.** s
35d30 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 ome circumstance
35d40 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 s the associated
35d50 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 metadata may be
35d60 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 preserved. An
35d70 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 example.** of wh
35d80 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 ere this might b
35d90 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 e useful is in a
35da0 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 regular-express
35db0 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 ion matching.**
35dc0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f function. The co
35dd0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f mpiled version o
35de0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 f the regular ex
35df0 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 pression can be
35e00 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 stored as.** met
35e10 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 adata associated
35e20 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72 with the patter
35e30 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 n string. .** T
35e40 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 hen as long as t
35e50 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e he pattern strin
35e60 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 g remains the sa
35e70 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 me,.** the compi
35e80 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 led regular expr
35e90 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 ession can be re
35ea0 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 used on multiple
35eb0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 .** invocations
35ec0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 of the same func
35ed0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tion..**.** ^The
35ee0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 sqlite3_get_aux
35ef0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 data() interface
35f00 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
35f10 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 er to the metada
35f20 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 ta.** associated
35f30 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
35f40 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 set_auxdata() fu
35f50 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 nction with the
35f60 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 Nth argument.**
35f70 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 value to the app
35f80 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
35f90 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 function. ^If t
35fa0 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 here is no metad
35fb0 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ata.** associate
35fc0 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 d with the funct
35fd0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 ion argument, th
35fe0 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 is sqlite3_get_a
35ff0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
36000 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 ce.** returns a
36010 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
36020 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
36030 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e _set_auxdata(C,N
36040 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 ,P,X) interface
36050 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 saves P as metad
36060 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 ata for the N-th
36070 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 .** argument of
36080 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
36090 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
360a0 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a . ^Subsequent.*
360b0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 * calls to sqlit
360c0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 e3_get_auxdata(C
360d0 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f ,N) return P fro
360e0 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e m the most recen
360f0 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 t.** sqlite3_set
36100 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 _auxdata(C,N,P,X
36110 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 ) call if the me
36120 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 tadata is still
36130 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c valid or.** NULL
36140 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 if the metadata
36150 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 has been discar
36160 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 ded..** ^After e
36170 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ach call to sqli
36180 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
36190 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 C,N,P,X) where X
361a0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a is not NULL,.**
361b0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 SQLite will inv
361c0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
361d0 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 or function X wi
361e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 th parameter P e
361f0 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 xactly.** once,
36200 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 when the metadat
36210 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a a is discarded..
36220 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 ** SQLite is fre
36230 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 e to discard the
36240 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 metadata at any
36250 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 time, including
36260 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 : <ul>.** <li> w
36270 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f hen the correspo
36280 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 nding function p
36290 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 arameter changes
362a0 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 , or.** <li> whe
362b0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 n [sqlite3_reset
362c0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
362d0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 finalize()] is c
362e0 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a alled for the.**
362f0 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d SQL statem
36300 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 ent, or.** <li>
36310 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 when sqlite3_set
36320 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e _auxdata() is in
36330 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 voked again on t
36340 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 he same paramete
36350 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 r, or.** <li> du
36360 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 ring the origina
36370 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 l sqlite3_set_au
36380 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 xdata() call whe
36390 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 n a memory .**
363a0 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 allocation e
363b0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 rror occurs. </u
363c0 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 l>)^.**.** Note
363d0 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 the last bullet
363e0 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 in particular.
363f0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 The destructor X
36400 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f in .** sqlite3_
36410 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c set_auxdata(C,N,
36420 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61 P,X) might be ca
36430 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 lled immediately
36440 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 , before the.**
36450 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
36460 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
36470 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 even returns. H
36480 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74 ence sqlite3_set
36490 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 _auxdata().** sh
364a0 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e ould be called n
364b0 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74 ear the end of t
364c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c he function impl
364d0 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 ementation and t
364e0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 he.** function i
364f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 mplementation sh
36500 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e ould not make an
36510 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72 y use of P after
36520 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f .** sqlite3_set_
36530 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65 auxdata() has be
36540 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a en called..**.**
36550 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 ^(In practice,
36560 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 metadata is pres
36570 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 erved between fu
36580 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 nction calls for
36590 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 .** function par
365a0 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 ameters that are
365b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f compile-time co
365c0 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 nstants, includi
365d0 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 ng literal.** va
365e0 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 lues and [parame
365f0 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73 ters] and expres
36600 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 sions composed f
36610 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a rom the same.)^.
36620 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
36630 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c ines must be cal
36640 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
36650 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
36660 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e h.** the SQL fun
36670 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
36680 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
36690 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 void *SQLITE_STD
366a0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 65 74 CALL sqlite3_get
366b0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 _auxdata(sqlite3
366c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e _context*, int N
366d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
366e0 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c id SQLITE_STDCAL
366f0 4c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 L sqlite3_set_au
36700 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f xdata(sqlite3_co
36710 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 ntext*, int N, v
36720 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 oid*, void (*)(v
36730 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 oid*));.../*.**
36740 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 CAPI3REF: Consta
36750 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 nts Defining Spe
36760 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 cial Destructor
36770 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 Behavior.**.** T
36780 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c hese are special
36790 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 values for the
367a0 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 destructor that
367b0 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 is passed in as
367c0 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 the.** final arg
367d0 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 ument to routine
367e0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f s like [sqlite3_
367f0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 result_blob()].
36800 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 ^If the destruc
36810 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 tor.** argument
36820 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 is SQLITE_STATIC
36830 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 , it means that
36840 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e the content poin
36850 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a ter is constant.
36860 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 ** and will neve
36870 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f r change. It do
36880 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 es not need to b
36890 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 e destroyed. ^T
368a0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 he.** SQLITE_TRA
368b0 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 NSIENT value mea
368c0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 ns that the cont
368d0 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 ent will likely
368e0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 change in.** the
368f0 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 near future and
36900 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f that SQLite sho
36910 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e uld make its own
36920 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
36930 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 .** the content
36940 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 before returning
36950 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 ..**.** The type
36960 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 def is necessary
36970 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 to work around
36980 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 problems in cert
36990 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 ain.** C++ compi
369a0 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 lers..*/.typedef
369b0 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f void (*sqlite3_
369c0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
369d0 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 (void*);.#define
369e0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 SQLITE_STATIC
369f0 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 ((sqlite3_de
36a00 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 structor_type)0)
36a10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
36a20 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 TRANSIENT ((sq
36a30 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 lite3_destructor
36a40 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a _type)-1)../*.**
36a50 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 CAPI3REF: Setti
36a60 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 ng The Result Of
36a70 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e An SQL Function
36a80 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
36a90 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a te3_context.**.*
36aa0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
36ab0 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 are used by the
36ac0 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c xFunc or xFinal
36ad0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a callbacks that.
36ae0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c ** implement SQL
36af0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
36b00 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a ggregates. See.
36b10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
36b20 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 te_function()] a
36b30 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
36b40 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
36b50 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e .** for addition
36b60 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
36b70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 **.** These func
36b80 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 tions work very
36b90 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 much like the [p
36ba0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 arameter binding
36bb0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 ] family of.** f
36bc0 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f unctions used to
36bd0 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 bind values to
36be0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 host parameters
36bf0 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 in prepared stat
36c00 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 ements..** Refer
36c10 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 to the [SQL par
36c20 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 ameter] document
36c30 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
36c40 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
36c50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
36c60 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
36c70 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
36c80 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f s the result fro
36c90 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 m.** an applicat
36ca0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
36cb0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 tion to be the B
36cc0 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e LOB whose conten
36cd0 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 t is pointed.**
36ce0 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 to by the second
36cf0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 parameter and w
36d00 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 hich is N bytes
36d10 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 long where N is
36d20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 the.** third par
36d30 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ameter..**.** ^T
36d40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
36d50 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 61 6e 64 t_zeroblob() and
36d60 20 7a 65 72 6f 62 6c 6f 62 36 34 28 29 20 69 6e zeroblob64() in
36d70 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 terfaces set the
36d80 20 72 65 73 75 6c 74 20 0a 2a 2a 20 6f 66 20 74 result .** of t
36d90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
36da0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
36db0 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e to be a BLOB con
36dc0 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f taining all zero
36dd0 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 .** bytes and N
36de0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 bytes in size, w
36df0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 here N is the va
36e00 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 lue of the 2nd p
36e10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
36e20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
36e30 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 ult_double() int
36e40 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
36e50 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 result from.** a
36e60 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
36e70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
36e80 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 o be a floating
36e90 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 point value spec
36ea0 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 ified.** by its
36eb0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 2nd argument..**
36ec0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
36ed0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
36ee0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 and sqlite3_resu
36ef0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e lt_error16() fun
36f00 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 ctions.** cause
36f10 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 the implemented
36f20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
36f30 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 throw an excepti
36f40 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 on..** ^SQLite u
36f50 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 ses the string p
36f60 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 ointed to by the
36f70 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 .** 2nd paramete
36f80 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 r of sqlite3_res
36f90 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 ult_error() or s
36fa0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
36fb0 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 ror16().** as th
36fc0 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 e text of an err
36fd0 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 or message. ^SQ
36fe0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 Lite interprets
36ff0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 the error.** mes
37000 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d sage string from
37010 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37020 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 error() as UTF-8
37030 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 . ^SQLite.** int
37040 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 erprets the stri
37050 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ng from sqlite3_
37060 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
37070 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 as UTF-16 in na
37080 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 tive.** byte ord
37090 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 er. ^If the thi
370a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
370b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
370c0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c rror().** or sql
370d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
370e0 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 r16() is negativ
370f0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 e then SQLite ta
37100 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 kes as the error
37110 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 .** message all
37120 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 text up through
37130 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 the first zero c
37140 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 haracter..** ^If
37150 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
37160 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
37170 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f result_error() o
37180 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 r.** sqlite3_res
37190 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 ult_error16() is
371a0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 non-negative th
371b0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 en SQLite takes
371c0 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 that many.** byt
371d0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 es (not characte
371e0 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 rs) from the 2nd
371f0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 parameter as th
37200 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e e error message.
37210 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
37220 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
37230 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 and sqlite3_resu
37240 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 lt_error16().**
37250 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 routines make a
37260 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 private copy of
37270 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
37280 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a e text before.**
37290 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 they return. H
372a0 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e ence, the callin
372b0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 g function can d
372c0 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 eallocate or.**
372d0 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 modify the text
372e0 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 after they retur
372f0 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a n without harm..
37300 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
37310 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 result_error_cod
37320 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 e() function cha
37330 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 nges the error c
37340 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 ode.** returned
37350 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 by SQLite as a r
37360 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f esult of an erro
37370 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e r in a function.
37380 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a ^By default,.*
37390 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 * the error code
373a0 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 is SQLITE_ERROR
373b0 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 . ^A subsequent
373c0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
373d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a _result_error().
373e0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
373f0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 sult_error16() r
37400 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 esets the error
37410 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 code to SQLITE_E
37420 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 RROR..**.** ^The
37430 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37440 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 error_toobig() i
37450 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 nterface causes
37460 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 SQLite to throw
37470 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 an.** error indi
37480 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 cating that a st
37490 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 ring or BLOB is
374a0 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 too long to repr
374b0 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 esent..**.** ^Th
374c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
374d0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 _error_nomem() i
374e0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 nterface causes
374f0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 SQLite to throw
37500 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 an.** error indi
37510 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 cating that a me
37520 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
37530 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 failed..**.** ^T
37540 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
37550 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 t_int() interfac
37560 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 e sets the retur
37570 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 n value.** of th
37580 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
37590 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
375a0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 o be the 32-bit
375b0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a signed integer.*
375c0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e * value given in
375d0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e the 2nd argumen
375e0 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 t..** ^The sqlit
375f0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 e3_result_int64(
37600 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
37610 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
37620 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c e.** of the appl
37630 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
37640 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 function to be t
37650 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 he 64-bit signed
37660 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 integer.** valu
37670 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 e given in the 2
37680 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
37690 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
376a0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e result_null() in
376b0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
376c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a return value.**
376d0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
376e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
376f0 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e tion to be NULL.
37700 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
37710 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 te3_result_text(
37720 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ), sqlite3_resul
37730 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 t_text16(),.** s
37740 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
37750 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 xt16le(), and sq
37760 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
37770 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 t16be() interfac
37780 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 es.** set the re
37790 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
377a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
377b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
377c0 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 o be.** a text s
377d0 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 tring which is r
377e0 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 epresented as UT
377f0 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 F-8, UTF-16 nati
37800 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a ve byte order,.*
37810 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 * UTF-16 little
37820 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 endian, or UTF-1
37830 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 6 big endian, re
37840 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e spectively..** ^
37850 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
37860 6c 74 5f 74 65 78 74 36 34 28 29 20 69 6e 74 65 lt_text64() inte
37870 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
37880 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 eturn value of a
37890 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e n.** application
378a0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
378b0 6e 20 74 6f 20 62 65 20 61 20 74 65 78 74 20 73 n to be a text s
378c0 74 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e 63 6f tring in an enco
378d0 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66 69 65 ding.** specifie
378e0 64 20 62 79 20 74 68 65 20 66 69 66 74 68 20 28 d by the fifth (
378f0 61 6e 64 20 6c 61 73 74 29 20 70 61 72 61 6d 65 and last) parame
37900 74 65 72 2c 20 77 68 69 63 68 20 6d 75 73 74 20 ter, which must
37910 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 be one.** of [SQ
37920 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c LITE_UTF8], [SQL
37930 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c ITE_UTF16], [SQL
37940 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 ITE_UTF16BE], or
37950 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 [SQLITE_UTF16LE
37960 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 ]..** ^SQLite ta
37970 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 kes the text res
37980 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 ult from the app
37990 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a lication from.**
379a0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
379b0 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 er of the sqlite
379c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
379d0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 nterfaces..** ^I
379e0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 f the 3rd parame
379f0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
37a00 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
37a10 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 interfaces.** is
37a20 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
37a30 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 SQLite takes res
37a40 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 ult text from th
37a50 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a e 2nd parameter.
37a60 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 ** through the f
37a70 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 irst zero charac
37a80 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ter..** ^If the
37a90 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
37aa0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
37ab0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
37ac0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e aces.** is non-n
37ad0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 egative, then as
37ae0 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 many bytes (not
37af0 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 characters) of
37b00 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e the text.** poin
37b10 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e ted to by the 2n
37b20 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 d parameter are
37b30 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 taken as the app
37b40 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
37b50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 .** function res
37b60 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 ult. If the 3rd
37b70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f parameter is no
37b80 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e n-negative, then
37b90 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 it.** must be t
37ba0 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 he byte offset i
37bb0 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 nto the string w
37bc0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 here the NUL ter
37bd0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a minator would.**
37be0 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73 appear if the s
37bf0 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 tring where NUL
37c00 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 terminated. If
37c10 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 any NUL characte
37c20 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 rs occur.** in t
37c30 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 he string at a b
37c40 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 yte offset that
37c50 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 is less than the
37c60 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 value of the 3r
37c70 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 d.** parameter,
37c80 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 then the resulti
37c90 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 ng string will c
37ca0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 ontain embedded
37cb0 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 NULs and the.**
37cc0 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 result of expres
37cd0 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 sions operating
37ce0 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 on strings with
37cf0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 embedded NULs is
37d00 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e undefined..** ^
37d10 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d If the 4th param
37d20 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
37d30 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
37d40 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f interfaces.** o
37d50 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
37d60 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e _blob is a non-N
37d70 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
37d80 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 n SQLite calls t
37d90 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 hat.** function
37da0 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f as the destructo
37db0 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 r on the text or
37dc0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 BLOB result whe
37dd0 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 n it has.** fini
37de0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 shed using that
37df0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 result..** ^If t
37e00 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
37e10 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
37e20 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
37e30 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a erfaces or to.**
37e40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37e50 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 blob is the spec
37e60 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c ial constant SQL
37e70 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e ITE_STATIC, then
37e80 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d SQLite.** assum
37e90 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 es that the text
37ea0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 or BLOB result
37eb0 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 is in constant s
37ec0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f pace and does no
37ed0 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f t.** copy the co
37ee0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 ntent of the par
37ef0 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 ameter nor call
37f00 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 a destructor on
37f10 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 the content.** w
37f20 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 hen it has finis
37f30 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 hed using that r
37f40 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 esult..** ^If th
37f50 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
37f60 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
37f70 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
37f80 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c rfaces.** or sql
37f90 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
37fa0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 is the special
37fb0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f constant SQLITE_
37fc0 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 TRANSIENT.** the
37fd0 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 n SQLite makes a
37fe0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 copy of the res
37ff0 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f ult into space o
38000 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 btained from.**
38010 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
38020 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 lloc()] before i
38030 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a t returns..**.**
38040 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
38050 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 sult_value() int
38060 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
38070 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 result of.** the
38080 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
38090 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
380a0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 be a copy of th
380b0 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 e.** [unprotecte
380c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
380d0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 object specifie
380e0 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 d by the 2nd par
380f0 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a ameter. ^The.**
38100 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
38110 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 value() interfac
38120 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
38130 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 f the [sqlite3_v
38140 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 alue].** so that
38150 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
38160 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 lue] specified i
38170 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 n the parameter
38180 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a may change or.**
38190 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
381a0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 after sqlite3_re
381b0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 sult_value() ret
381c0 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 urns without har
381d0 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 m..** ^A [protec
381e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
381f0 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c e] object may al
38200 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 ways be used whe
38210 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 re an.** [unprot
38220 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
38230 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 lue] object is r
38240 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 equired, so eith
38250 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 er.** kind of [s
38260 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
38270 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 ject can be used
38280 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 with this inter
38290 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 face..**.** If t
382a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
382b0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 e called from wi
382c0 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 thin the differe
382d0 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 nt thread.** tha
382e0 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 n the one contai
382f0 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 ning the applica
38300 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
38310 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 ction that recei
38320 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 ved.** the [sqli
38330 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 te3_context] poi
38340 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 nter, the result
38350 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
38360 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
38370 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 oid SQLITE_STDCA
38380 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c LL sqlite3_resul
38390 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 t_blob(sqlite3_c
383a0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
383b0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 oid*, int, void(
383c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
383d0 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 TE_API void SQLI
383e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
383f0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 36 34 e3_result_blob64
38400 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
38410 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 0a 20 *,const void*,.
38420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
38430 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 sqlite
38440 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64 28 2a 29 3_uint64,void(*)
38450 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 (void*));.SQLITE
38460 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 _API void SQLITE
38470 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
38480 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 _result_double(s
38490 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
384a0 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 double);.SQLITE
384b0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 _API void SQLITE
384c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
384d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 _result_error(sq
384e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
384f0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 const char*, int
38500 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
38510 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c id SQLITE_STDCAL
38520 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 L sqlite3_result
38530 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 _error16(sqlite3
38540 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
38550 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 void*, int);.SQ
38560 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 LITE_API void SQ
38570 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
38580 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
38590 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 r_toobig(sqlite3
385a0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 _context*);.SQLI
385b0 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 TE_API void SQLI
385c0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
385d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
385e0 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f nomem(sqlite3_co
385f0 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f ntext*);.SQLITE_
38600 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f API void SQLITE_
38610 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
38620 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 result_error_cod
38630 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
38640 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 t*, int);.SQLITE
38650 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 _API void SQLITE
38660 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
38670 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 _result_int(sqli
38680 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
38690 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 t);.SQLITE_API v
386a0 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 oid SQLITE_STDCA
386b0 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c LL sqlite3_resul
386c0 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f t_int64(sqlite3_
386d0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 context*, sqlite
386e0 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 3_int64);.SQLITE
386f0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 _API void SQLITE
38700 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
38710 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c _result_null(sql
38720 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
38730 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
38740 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
38750 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
38760 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 xt(sqlite3_conte
38770 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a xt*, const char*
38780 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
38790 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
3