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 2d 2d 56 45 52 53 2d 2d 22 0a "--VERS--".
10b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 #define SQLITE_V
10c0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d ERSION_NUMBER --
10d0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d VERSION-NUMBER--
10e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
10f0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 SOURCE_ID "
1100: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a --SOURCE-ID--"..
1110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1120: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 Run-Time Library
1130: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 Version Numbers
1140: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 .** KEYWORDS: sq
1150: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 lite3_version, s
1160: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a qlite3_sourceid.
1170: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 **.** These inte
1180: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 rfaces provide t
1190: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 he same informat
11a0: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 ion as the [SQLI
11b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 TE_VERSION],.**
11c0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f [SQLITE_VERSION_
11d0: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 NUMBER], and [SQ
11e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 LITE_SOURCE_ID]
11f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
1200: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 acros.** but are
1210: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
1220: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 the library ins
1230: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 tead of the head
1240: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 er file. ^(Caut
1250: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d ious.** programm
1260: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 ers might includ
1270: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 e assert() state
1280: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 ments in their a
1290: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a pplication to.**
12a0: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c verify that val
12b0: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ues returned by
12c0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
12d0: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f match the macro
12e0: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 s in.** the head
12f0: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 er, and thus ens
1300: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 ure that the app
1310: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 lication is.** c
1320: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 ompiled with mat
1330: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e ching library an
1340: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a d header files..
1350: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1360: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 e><pre>.** asser
1370: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 t( sqlite3_libve
1380: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d rsion_number()==
1390: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
13a0: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 UMBER );.** asse
13b0: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 rt( strcmp(sqlit
13c0: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 e3_sourceid(),SQ
13d0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d LITE_SOURCE_ID)=
13e0: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 =0 );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f strcmp(sqlite3_
1400: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c libversion(),SQL
1410: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 ITE_VERSION)==0
1420: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
1430: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a ockquote>)^.**.*
1440: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 * ^The sqlite3_v
1450: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 ersion[] string
1460: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e constant contain
1470: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 s the text of [S
1480: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a QLITE_VERSION].*
1490: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 * macro. ^The s
14a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
14b0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 n() function ret
14c0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
14d0: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 o the.** to the
14e0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b sqlite3_version[
14f0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e ] string constan
1500: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f t. The sqlite3_
1510: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 libversion().**
1520: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 function is prov
1530: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 ided for use in
1540: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 DLLs since DLL u
1550: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 sers usually do
1560: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 not have.** dire
1570: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 ct access to str
1580: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 ing constants wi
1590: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e thin the DLL. ^
15a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c The.** sqlite3_l
15b0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
15c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 () function retu
15d0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 rns an integer e
15e0: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 qual to.** [SQLI
15f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
1600: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 R]. ^The sqlite
1610: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 3_sourceid() fun
1620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a ction returns .*
1630: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * a pointer to a
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
1650: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 whose value is
1660: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 the same as the
1670: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 .** [SQLITE_SOUR
1680: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 CE_ID] C preproc
1690: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a essor macro..**.
16a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
16b0: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 lite_version()]
16c0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 and [sqlite_sour
16d0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c ce_id()]..*/.SQL
16e0: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 ITE_EXTERN const
16f0: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 char sqlite3_ve
1700: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 rsion[];.const c
1710: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 har *sqlite3_lib
1720: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 version(void);.c
1730: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
1740: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 e3_sourceid(void
1750: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c );.int sqlite3_l
1760: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
1770: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 (void);../*.** C
1780: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d API3REF: Run-Tim
1790: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c e Library Compil
17a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 ation Options Di
17b0: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 agnostics.**.**
17c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d ^The sqlite3_com
17d0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 pileoption_used(
17e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 ) function retur
17f0: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e ns 0 or 1 .** in
1800: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 dicating whether
1810: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f the specified o
1820: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 ption was define
1830: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 d at .** compile
1840: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c time. ^The SQL
1850: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 ITE_ prefix may
1860: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 be omitted from
1870: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e the .** option n
1880: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 ame passed to sq
1890: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
18a0: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a ion_used(). .**
18b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
18c0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
18d0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c et() function al
18e0: 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a lows iterating.*
18f0: 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 * over the list
1900: 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 of options that
1910: 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 were defined at
1920: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a compile time by.
1930: 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 ** returning the
1940: 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 N-th compile ti
1950: 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 me option string
1960: 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 . ^If N is out
1970: 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c of range,.** sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 on_get() returns
19a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
19b0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a ^The SQLITE_ .
19c0: 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 ** prefix is omi
19d0: 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 tted from any st
19e0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 rings returned b
19f0: 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f y .** sqlite3_co
1a00: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
1a10: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 )..**.** ^Suppor
1a20: 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f t for the diagno
1a30: 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 stic functions s
1a40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
1a50: 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 tion_used().** a
1a60: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 nd sqlite3_compi
1a70: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d leoption_get() m
1a80: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 ay be omitted by
1a90: 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 specifying the
1aa0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 .** [SQLITE_OMIT
1ab0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 _COMPILEOPTION_D
1ac0: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 IAGS] option at
1ad0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a compile time..**
1ae0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 .** See also: SQ
1af0: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c L functions [sql
1b00: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f ite_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a n_used()] and.**
1b20: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 [sqlite_compile
1b30: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e option_get()] an
1b40: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f d the [compile_o
1b50: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a ptions pragma]..
1b60: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 */.#ifndef SQLIT
1b70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 E_OMIT_COMPILEOP
1b80: 54 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 TION_DIAGS.int s
1b90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
1ba0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 tion_used(const
1bb0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b char *zOptName);
1bc0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1bd0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
1be0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 on_get(int N);.#
1bf0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
1c00: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 I3REF: Test To S
1c10: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 ee If The Librar
1c20: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a y Is Threadsafe.
1c30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1c40: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 e3_threadsafe()
1c50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
1c60: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c zero if and onl
1c70: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 y if.** SQLite w
1c80: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
1c90: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f mutexing code o
1ca0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 mitted due to th
1cb0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 e.** [SQLITE_THR
1cc0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 EADSAFE] compile
1cd0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 -time option bei
1ce0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a ng set to 0..**.
1cf0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 ** SQLite can be
1d00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f compiled with o
1d10: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 r without mutexe
1d20: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 s. When.** the
1d30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
1d40: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 FE] C preprocess
1d50: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 or macro is 1 or
1d60: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 2, mutexes.** a
1d70: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 re enabled and S
1d80: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 QLite is threads
1d90: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a afe. When the.*
1da0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 * [SQLITE_THREAD
1db0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 SAFE] macro is 0
1dc0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 , .** the mutexe
1dd0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 s are omitted.
1de0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 Without the mute
1df0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 xes, it is not s
1e00: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 afe.** to use SQ
1e10: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c Lite concurrentl
1e20: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e y from more than
1e30: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a one thread..**.
1e40: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 ** Enabling mute
1e50: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 xes incurs a mea
1e60: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 surable performa
1e70: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 nce penalty..**
1e80: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f So if speed is o
1e90: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 f utmost importa
1ea0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 nce, it makes se
1eb0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a nse to disable.*
1ec0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 * the mutexes.
1ed0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 But for maximum
1ee0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 safety, mutexes
1ef0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 should be enable
1f00: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 d..** ^The defau
1f10: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 lt behavior is f
1f20: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 or mutexes to be
1f30: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 enabled..**.**
1f40: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 This interface c
1f50: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e an be used by an
1f60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 application to
1f70: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 make sure that t
1f80: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 he.** version of
1f90: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 SQLite that it
1fa0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e is linking again
1fb0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 st was compiled
1fc0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 with.** the desi
1fd0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 red setting of t
1fe0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
1ff0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a DSAFE] macro..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
2010: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 ce only reports
2020: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 on the compile-t
2030: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e ime mutex settin
2040: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c g.** of the [SQL
2050: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
2060: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 flag. If SQLite
2070: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
2080: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 h.** SQLITE_THRE
2090: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 ADSAFE=1 or =2 t
20a0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 hen mutexes are
20b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 enabled by defau
20c0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 lt but.** can be
20d0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 fully or partia
20e0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 lly disabled usi
20f0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 ng a call to [sq
2100: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a lite3_config()].
2110: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 ** with the verb
2120: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 s [SQLITE_CONFIG
2130: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 _SINGLETHREAD],
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
2150: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 ULTITHREAD],.**
2160: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
2170: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 G_SERIALIZED].
2180: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c ^(The return val
2190: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c ue of the.** sql
21a0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
21b0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 ) function shows
21c0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c only the compil
21d0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f e-time setting o
21e0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 f.** thread safe
21f0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d ty, not any run-
2200: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 time changes to
2210: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 that setting mad
2220: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f e by.** sqlite3_
2230: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 config(). In oth
2240: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 er words, the re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 turn value from
2260: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 sqlite3_threadsa
2270: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 fe().** is uncha
2280: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f nged by calls to
2290: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
22a0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 ).)^.**.** See t
22b0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f he [threading mo
22c0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f de] documentatio
22d0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c n for additional
22e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f information..*/
22f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 .int sqlite3_thr
2300: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a eadsafe(void);..
2310: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2320: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
2330: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 ion Handle.** KE
2340: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 YWORDS: {databas
2350: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 e connection} {d
2360: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2370: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 ons}.**.** Each
2380: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 open SQLite data
2390: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e base is represen
23a0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 ted by a pointer
23b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
23c0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 of.** the opaque
23d0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 structure named
23e0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 "sqlite3". It
23f0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 is useful to thi
2400: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 nk of an sqlite3
2410: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 .** pointer as a
2420: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b n object. The [
2430: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
2450: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
2460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
2470: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 interfaces are i
2480: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c ts constructors,
2490: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c and [sqlite3_cl
24a0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ose()].** and [s
24b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
24c0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 )] are its destr
24d0: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 uctors. There a
24e0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a re many other.**
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 interfaces (suc
2500: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 h as.** [sqlite3
2510: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 _prepare_v2()],
2520: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2530: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 function()], and
2540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 .** [sqlite3_bus
2550: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 y_timeout()] to
2560: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 name but three)
2570: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 that are methods
2580: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 on an.** sqlite
2590: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 3 object..*/.typ
25a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
25b0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a te3 sqlite3;../*
25c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 .** CAPI3REF: 64
25d0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 -Bit Integer Typ
25e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
25f0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c sqlite_int64 sql
2600: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a ite_uint64.**.**
2610: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 Because there i
2620: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 s no cross-platf
2630: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 orm way to speci
2640: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 fy 64-bit intege
2650: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 r types.** SQLit
2660: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 e includes typed
2670: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 efs for 64-bit s
2680: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e igned and unsign
2690: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a ed integers..**.
26a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 ** The sqlite3_i
26b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 nt64 and sqlite3
26c0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 _uint64 are the
26d0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 preferred type d
26e0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 efinitions..** T
26f0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 he sqlite_int64
2700: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 and sqlite_uint6
2710: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 4 types are supp
2720: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 orted for backwa
2730: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 rds.** compatibi
2740: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a lity only..**.**
2750: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
2760: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 t64 and sqlite_i
2770: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 nt64 types can s
2780: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c tore integer val
2790: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d ues.** between -
27a0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 9223372036854775
27b0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 808 and +9223372
27c0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 036854775807 inc
27d0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a lusive. ^The.**
27e0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 sqlite3_uint64
27f0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 and sqlite_uint6
2800: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 4 types can stor
2810: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
2820: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 .** between 0 a
2830: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 nd +184467440737
2840: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 09551615 inclusi
2850: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 ve..*/.#ifdef SQ
2860: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a LITE_INT64_TYPE.
2870: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 typedef SQLITE
2880: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 _INT64_TYPE sqli
2890: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 te_int64;. type
28a0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c def unsigned SQL
28b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 ITE_INT64_TYPE s
28c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 qlite_uint64;.#e
28d0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 lif defined(_MSC
28e0: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 _VER) || defined
28f0: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 (__BORLANDC__).
2900: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 typedef __int64
2910: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
2920: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
2930: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 d __int64 sqlite
2940: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 _uint64;.#else.
2950: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f typedef long lo
2960: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e ng int sqlite_in
2970: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 t64;. typedef u
2980: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e nsigned long lon
2990: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e g int sqlite_uin
29a0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 t64;.#endif.type
29b0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 def sqlite_int64
29c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a sqlite3_int64;.
29d0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 typedef sqlite_u
29e0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 int64 sqlite3_ui
29f0: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 nt64;../*.** If
2a00: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 compiling for a
2a10: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c processor that l
2a20: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f acks floating po
2a30: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 int support,.**
2a40: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 substitute integ
2a50: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d er for floating-
2a60: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 point..*/.#ifdef
2a70: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f SQLITE_OMIT_FLO
2a80: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 ATING_POINT.# de
2a90: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 fine double sqli
2aa0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 te3_int64.#endif
2ab0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2ac0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 : Closing A Data
2ad0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a base Connection.
2ae0: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 ** DESTRUCTOR: s
2af0: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
2b00: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 e sqlite3_close(
2b10: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c ) and sqlite3_cl
2b20: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 ose_v2() routine
2b30: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 s are destructor
2b40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 s.** for the [sq
2b50: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a lite3] object..*
2b60: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 * ^Calls to sqli
2b70: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 te3_close() and
2b80: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
2b90: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 () return [SQLIT
2ba0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 E_OK] if.** the
2bb0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
2bc0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 is successfully
2bd0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 destroyed and a
2be0: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a ll associated.**
2bf0: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 resources are d
2c00: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a eallocated..**.*
2c10: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 * ^If the databa
2c20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
2c30: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
2c40: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 unfinalized pre
2c50: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
2c60: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 nts or unfinishe
2c70: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 d sqlite3_backup
2c80: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 objects then sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a lite3_close().**
2ca0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 will leave the
2cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2cc0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 ion open and ret
2cd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 urn [SQLITE_BUSY
2ce0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 ]..** ^If sqlite
2cf0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 3_close_v2() is
2d00: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 called with unfi
2d10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 nalized prepared
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 statements.** a
2d30: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 nd/or unfinished
2d40: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 sqlite3_backups
2d50: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 , then the datab
2d60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 ase connection b
2d70: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 ecomes.** an unu
2d80: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 sable "zombie" w
2d90: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 hich will automa
2da0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c tically be deall
2db0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a ocated when the.
2dc0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 ** last prepared
2dd0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 statement is fi
2de0: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c nalized or the l
2df0: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b ast sqlite3_back
2e00: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 up is.** finishe
2e10: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f d. The sqlite3_
2e20: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 close_v2() inter
2e30: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 face is intended
2e40: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a for use with.**
2e50: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 host languages
2e60: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65 that are garbage
2e70: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 collected, and
2e80: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 where the order
2e90: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 in which.** dest
2ea0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c ructors are call
2eb0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e ed is arbitrary.
2ec0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
2ed0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 ons should [sqli
2ee0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 te3_finalize | f
2ef0: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 inalize] all [pr
2f00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2f10: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f s],.** [sqlite3_
2f20: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f blob_close | clo
2f30: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 se] all [BLOB ha
2f40: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 ndles], and .**
2f50: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f [sqlite3_backup_
2f60: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d finish | finish]
2f70: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 all [sqlite3_ba
2f80: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 ckup] objects as
2f90: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 sociated.** with
2fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
2fb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 bject prior to a
2fc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f ttempting to clo
2fd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 se the object.
2fe0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 ^If.** sqlite3_c
2ff0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c lose_v2() is cal
3000: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 led on a [databa
3010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
3020: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a hat still has.**
3030: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 outstanding [pr
3040: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
3050: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 s], [BLOB handle
3060: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 s], and/or.** [s
3070: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
3080: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 bjects then it r
3090: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
30a0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c K] and the deall
30b0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 ocation.** of re
30c0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72 sources is defer
30d0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 red until all [p
30e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
30f0: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c ts], [BLOB handl
3100: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c es],.** and [sql
3110: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a ite3_backup] obj
3120: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 ects are also de
3130: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e stroyed..**.** ^
3140: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 If an [sqlite3]
3150: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f object is destro
3160: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e yed while a tran
3170: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c saction is open,
3180: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 .** the transact
3190: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ion is automatic
31a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ally rolled back
31b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 ..**.** The C pa
31c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
31d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e te3_close(C)] an
31e0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 d [sqlite3_close
31f0: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 _v2(C)].** must
3200: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c be either a NULL
3210: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 .** pointer or a
3220: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 n [sqlite3] obje
3230: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 ct pointer obtai
3240: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
3250: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
3260: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
3270: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
3280: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 _open_v2()], and
3290: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 not previously
32a0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c closed..** ^Call
32b0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 ing sqlite3_clos
32c0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 e() or sqlite3_c
32d0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 lose_v2() with a
32e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
32f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 argument is a h
3300: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
3310: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c /.int sqlite3_cl
3320: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 ose(sqlite3*);.i
3330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 nt sqlite3_close
3340: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a _v2(sqlite3*);..
3350: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 /*.** The type f
3360: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 or a callback fu
3370: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 nction..** This
3380: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 is legacy and de
3390: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 precated. It is
33a0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 included for hi
33b0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 storical.** comp
33c0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 atibility and is
33d0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e not documented.
33e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 .*/.typedef int
33f0: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 (*sqlite3_callba
3400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 ck)(void*,int,ch
3410: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a ar**, char**);..
3420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3430: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 One-Step Query E
3440: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 xecution Interfa
3450: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ce.** METHOD: sq
3460: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 lite3.**.** The
3470: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
3480: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f nterface is a co
3490: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 nvenience wrappe
34a0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c r around.** [sql
34b0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
34c0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
34d0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 p()], and [sqlit
34e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a e3_finalize()],.
34f0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 ** that allows a
3500: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f n application to
3510: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 run multiple st
3520: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a atements of SQL.
3530: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e ** without havin
3540: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f g to use a lot o
3550: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a f C code. .**.**
3560: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
3570: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ec() interface r
3580: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 uns zero or more
3590: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a UTF-8 encoded,.
35a0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 ** semicolon-sep
35b0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d arate SQL statem
35c0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f ents passed into
35d0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e its 2nd argumen
35e0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e t,.** in the con
35f0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 text of the [dat
3600: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3610: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 ] passed in as i
3620: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 ts 1st.** argume
3630: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c nt. ^If the cal
3640: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f lback function o
3650: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 f the 3rd argume
3660: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 nt to.** sqlite3
3670: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e _exec() is not N
3680: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 ULL, then it is
3690: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 invoked for each
36a0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 result row.** c
36b0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 oming out of the
36c0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 evaluated SQL s
36d0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 tatements. ^The
36e0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 4th argument to
36f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3700: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 () is relayed th
3710: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 rough to the 1st
3720: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 argument of eac
3730: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e h.** callback in
3740: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 vocation. ^If t
3750: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e he callback poin
3760: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3770: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c xec().** is NULL
3780: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 , then no callba
3790: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b ck is ever invok
37a0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f ed and result ro
37b0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 ws are.** ignore
37c0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 d..**.** ^If an
37d0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 error occurs whi
37e0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 le evaluating th
37f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
3800: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 passed into.**
3810: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 sqlite3_exec(),
3820: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f then execution o
3830: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 f the current st
3840: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e atement stops an
3850: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 d.** subsequent
3860: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 statements are s
3870: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 kipped. ^If the
3880: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 .** is not NULL
38b0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d then any error m
38c0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 essage is writte
38d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 n into memory ob
38e0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
38f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
3900: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 ] and passed bac
3910: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 k through the 5t
3920: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 h parameter..**
3930: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 To avoid memory
3940: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 leaks, the appli
3950: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e cation should in
3960: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 voke [sqlite3_fr
3970: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f ee()].** on erro
3980: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
3990: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 s returned throu
39a0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d gh the 5th param
39b0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 eter of.** of sq
39c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 lite3_exec() aft
39d0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 er the error mes
39e0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e sage string is n
39f0: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e o longer needed.
3a00: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 .** ^If the 5th
3a10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
3a20: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e ite3_exec() is n
3a30: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 ot NULL and no e
3a40: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 rrors.** occur,
3a50: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 then sqlite3_exe
3a60: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 c() sets the poi
3a70: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 nter in its 5th
3a80: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
3a90: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 NULL before retu
3aa0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 rning..**.** ^If
3ab0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 an sqlite3_exec
3ac0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 () callback retu
3ad0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
3ae0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
3af0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
3b00: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 rns SQLITE_ABORT
3b10: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e without invokin
3b20: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 g the callback a
3b30: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 gain and.** with
3b40: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 out running any
3b50: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 subsequent SQL s
3b60: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
3b70: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 ^The 2nd argume
3b80: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
3b90: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 3_exec() callbac
3ba0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 k function is th
3bb0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 e.** number of c
3bc0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 olumns in the re
3bd0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 sult. ^The 3rd
3be0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a sqlite3_exec().*
3c00: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e * callback is an
3c10: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
3c20: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 rs to strings ob
3c30: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f tained as if fro
3c40: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f m.** [sqlite3_co
3c50: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e lumn_text()], on
3c60: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d e for each colum
3c70: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 n. ^If an eleme
3c80: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c nt of a.** resul
3c90: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 t row is NULL th
3ca0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e en the correspon
3cb0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e ding string poin
3cc0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 ter for the.** s
3cd0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 qlite3_exec() ca
3ce0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c llback is a NULL
3cf0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 pointer. ^The
3d00: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 4th argument to
3d10: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 the.** sqlite3_e
3d20: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 xec() callback i
3d30: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
3d40: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 inters to string
3d50: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 s where each.**
3d60: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 entry represents
3d70: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 the name of cor
3d80: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c responding resul
3d90: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 t column as obta
3da0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 ined.** from [sq
3db0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
3dc0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 e()]..**.** ^If
3dd0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
3de0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
3df0: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f c() is a NULL po
3e00: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 inter, a pointer
3e10: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 .** to an empty
3e20: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 string, or a poi
3e30: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 nter that contai
3e40: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 ns only whitespa
3e50: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 ce and/or .** SQ
3e60: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e L comments, then
3e70: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e no SQL statemen
3e80: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 ts are evaluated
3e90: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 and the databas
3ea0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e e.** is not chan
3eb0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 ged..**.** Restr
3ec0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c ictions:.**.** <
3ed0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 ul>.** <li> The
3ee0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
3ef0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
3f00: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 1st parameter t
3f10: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
3f20: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 .** is a va
3f30: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 lid and open [da
3f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3f50: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 n]..** <li> The
3f60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
3f70: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b not close the [
3f80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3f90: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 ion] specified b
3fa0: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 y.** the 1s
3fb0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
3fc0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 qlite3_exec() wh
3fd0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ile sqlite3_exec
3fe0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a () is running..*
3ff0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 * <li> The appli
4000: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 cation must not
4010: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 modify the SQL s
4020: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 tatement text pa
4030: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 ssed into.**
4040: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 the 2nd parame
4050: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 ter of sqlite3_e
4060: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 xec() while sqli
4070: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 te3_exec() is ru
4080: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a nning..** </ul>.
4090: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 */.int sqlite3_e
40a0: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c xec(. sqlite3*,
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40d0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 /* An open dat
40e0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 abase */. const
40f0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 char *sql,
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4110: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 /* SQL to
4120: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a be evaluated */.
4130: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b int (*callback
4140: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 )(void*,int,char
4150: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 **,char**), /*
4160: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f Callback functio
4170: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 n */. void *,
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41a0: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e /* 1st argumen
41b0: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f t to callback */
41c0: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 . char **errmsg
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 20 20 20 20 20 2f 2a /*
41f0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 Error msg writt
4200: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f en here */.);../
4210: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
4220: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b esult Codes.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 EYWORDS: {result
4240: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e code definition
4250: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 s}.**.** Many SQ
4260: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 Lite functions r
4270: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 eturn an integer
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f result code fro
4290: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a m the set shown.
42a0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 ** here in order
42b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63 to indicate suc
42c0: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e cess or failure.
42d0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 .**.** New error
42e0: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 codes may be ad
42f0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 ded in future ve
4300: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
4310: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
4320: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 : [extended resu
4330: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 lt code definiti
4340: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ons].*/.#define
4350: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 SQLITE_OK
4360: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 0 /* Succe
4370: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a ssful result */.
4380: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d /* beginning-of-
4390: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 error-codes */.#
43a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 define SQLITE_ER
43b0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f ROR 1 /
43c0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d * SQL error or m
43d0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 issing database
43e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
43f0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 E_INTERNAL 2
4400: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c /* Internal l
4410: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 ogic error in SQ
4420: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 Lite */.#define
4430: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 SQLITE_PERM
4440: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 3 /* Acces
4450: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e s permission den
4460: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
4470: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 QLITE_ABORT
4480: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 4 /* Callba
4490: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 ck routine reque
44a0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f sted an abort */
44b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
44c0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 BUSY 5
44d0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
44e0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 file is locked
44f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4500: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 E_LOCKED 6
4510: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e /* A table in
4520: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
4530: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 locked */.#defi
4540: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 ne SQLITE_NOMEM
4550: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 7 /* A
4560: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 malloc() failed
4570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4580: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 E_READONLY 8
4590: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f /* Attempt to
45a0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c write a readonl
45b0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 y database */.#d
45c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
45d0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a ERRUPT 9 /*
45e0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 Operation termi
45f0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 nated by sqlite3
4600: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 _interrupt()*/.#
4610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4620: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f ERR 10 /
4630: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 * Some kind of d
4640: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 isk I/O error oc
4650: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e curred */.#defin
4660: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 e SQLITE_CORRUPT
4670: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 11 /* The
4680: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 database disk i
4690: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 mage is malforme
46a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
46b0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 ITE_NOTFOUND
46c0: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 12 /* Unknown
46d0: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 opcode in sqlite
46e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4700: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 TE_FULL 1
4710: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 3 /* Insertion
4720: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 failed because
4730: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c database is full
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4750: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 TE_CANTOPEN 1
4760: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 4 /* Unable to
4770: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 open the databa
4780: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 se file */.#defi
4790: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 ne SQLITE_PROTOC
47a0: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 OL 15 /* Da
47b0: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 tabase lock prot
47c0: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 ocol error */.#d
47d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 efine SQLITE_EMP
47e0: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a TY 16 /*
47f0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 Database is emp
4800: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ty */.#define SQ
4810: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 LITE_SCHEMA
4820: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 17 /* The dat
4830: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 abase schema cha
4840: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nged */.#define
4850: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 SQLITE_TOOBIG
4860: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 18 /* Strin
4870: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 g or BLOB exceed
4880: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a s size limit */.
4890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
48a0: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 ONSTRAINT 19
48b0: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 /* Abort due to
48c0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
48d0: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 tion */.#define
48e0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 SQLITE_MISMATCH
48f0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 20 /* Data
4900: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f type mismatch */
4910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4920: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 MISUSE 21
4930: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 /* Library used
4940: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a incorrectly */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
4960: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 OLFS 22
4970: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 /* Uses OS featu
4980: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 res not supporte
4990: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 d on host */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 fine SQLITE_AUTH
49b0: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
49c0: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 Authorization de
49d0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nied */.#define
49e0: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 SQLITE_FORMAT
49f0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 24 /* Auxil
4a00: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f iary database fo
4a10: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 rmat error */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e efine SQLITE_RAN
4a30: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a GE 25 /*
4a40: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 2nd parameter t
4a50: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f o sqlite3_bind o
4a60: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 ut of range */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
4a80: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f TADB 26 /
4a90: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 * File opened th
4aa0: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 at is not a data
4ab0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 base file */.#de
4ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 fine SQLITE_NOTI
4ad0: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 CE 27 /*
4ae0: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 Notifications fr
4af0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 om sqlite3_log()
4b00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4b10: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 TE_WARNING 2
4b20: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 8 /* Warnings
4b30: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 from sqlite3_log
4b40: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
4b50: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 LITE_ROW
4b60: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 100 /* sqlite3
4b70: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 _step() has anot
4b80: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f her row ready */
4b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4ba0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 DONE 101
4bb0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 /* sqlite3_step
4bc0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 () has finished
4bd0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 executing */./*
4be0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 end-of-error-cod
4bf0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 es */../*.** CAP
4c00: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 I3REF: Extended
4c10: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
4c20: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e KEYWORDS: {exten
4c30: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 ded result code
4c40: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a definitions}.**.
4c50: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c ** In its defaul
4c60: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c t configuration,
4c70: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 SQLite API rout
4c80: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 ines return one
4c90: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a of 30 integer.**
4ca0: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e [result codes].
4cb0: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 However, exper
4cc0: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 ience has shown
4cd0: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 that many of.**
4ce0: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 these result cod
4cf0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 es are too coars
4d00: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 e-grained. They
4d10: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 do not provide
4d20: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 as.** much infor
4d30: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f mation about pro
4d40: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d blems as program
4d50: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e mers might like.
4d60: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 In an effort t
4d70: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 o.** address thi
4d80: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e s, newer version
4d90: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 s of SQLite (ver
4da0: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c sion 3.3.8 and l
4db0: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a ater) include.**
4dc0: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 support for add
4dd0: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 itional result c
4de0: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 odes that provid
4df0: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 e more detailed
4e00: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 information.** a
4e10: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 bout errors. The
4e20: 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 se [extended res
4e30: 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 ult codes] are e
4e40: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c nabled or disabl
4e50: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 ed.** on a per d
4e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
4e70: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 on basis using t
4e80: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 he.** [sqlite3_e
4e90: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 xtended_result_c
4ea0: 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 odes()] API. Or
4eb0: 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 , the extended c
4ec0: 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d ode for.** the m
4ed0: 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 ost recent error
4ee0: 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 can be obtained
4ef0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
4f00: 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 e3_extended_errc
4f10: 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 ode()]..*/.#defi
4f20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
4f30: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 READ
4f40: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
4f50: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
4f60: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
4f70: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 HORT_READ
4f80: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
4f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
4fa0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 SQLITE_IOERR_WR
4fb0: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ITE
4fc0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4fd0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (3<<8)).#define
4fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 SQLITE_IOERR_FSY
4ff0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 NC (
5000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5010: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 4<<8)).#define S
5020: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f QLITE_IOERR_DIR_
5030: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 FSYNC (S
5040: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 QLITE_IOERR | (5
5050: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5060: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 LITE_IOERR_TRUNC
5070: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 ATE (SQ
5080: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c LITE_IOERR | (6<
5090: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
50a0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 ITE_IOERR_FSTAT
50b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
50c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c ITE_IOERR | (7<<
50d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
50e0: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 TE_IOERR_UNLOCK
50f0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
5100: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 TE_IOERR | (8<<8
5110: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5120: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 E_IOERR_RDLOCK
5130: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5140: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 E_IOERR | (9<<8)
5150: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5160: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 _IOERR_DELETE
5170: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5180: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 _IOERR | (10<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
51a0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 _IOERR_BLOCKED
51b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
51c0: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 _IOERR | (11<<8)
51d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
51e0: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 _IOERR_NOMEM
51f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5200: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 _IOERR | (12<<8)
5210: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5220: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 _IOERR_ACCESS
5230: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5240: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 _IOERR | (13<<8)
5250: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5260: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 _IOERR_CHECKRESE
5270: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 RVEDLOCK (SQLITE
5280: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 _IOERR | (14<<8)
5290: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
52a0: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 _IOERR_LOCK
52b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
52c0: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 _IOERR | (15<<8)
52d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
52e0: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 _IOERR_CLOSE
52f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5300: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 _IOERR | (16<<8)
5310: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5320: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 _IOERR_DIR_CLOSE
5330: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5340: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 _IOERR | (17<<8)
5350: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5360: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 _IOERR_SHMOPEN
5370: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5380: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 _IOERR | (18<<8)
5390: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
53a0: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 _IOERR_SHMSIZE
53b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
53c0: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 _IOERR | (19<<8)
53d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
53e0: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 _IOERR_SHMLOCK
53f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5400: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 _IOERR | (20<<8)
5410: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5420: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 _IOERR_SHMMAP
5430: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5440: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 _IOERR | (21<<8)
5450: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5460: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 _IOERR_SEEK
5470: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5480: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 _IOERR | (22<<8)
5490: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
54a0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f _IOERR_DELETE_NO
54b0: 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 ENT (SQLITE
54c0: 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 _IOERR | (23<<8)
54d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
54e0: 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 _IOERR_MMAP
54f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5500: 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 _IOERR | (24<<8)
5510: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5520: 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 _IOERR_GETTEMPPA
5530: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 TH (SQLITE
5540: 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 _IOERR | (25<<8)
5550: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5560: 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 _IOERR_CONVPATH
5570: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5580: 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 _IOERR | (26<<8)
5590: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
55a0: 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 _IOERR_VNODE
55b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
55c0: 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 _IOERR | (27<<8)
55d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
55e0: 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20 _IOERR_AUTH
55f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5600: 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 _IOERR | (28<<8)
5610: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5620: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 _LOCKED_SHAREDCA
5630: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 CHE (SQLITE
5640: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 _LOCKED | (1<<8
5650: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5660: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 E_BUSY_RECOVERY
5670: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5680: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c E_BUSY | (1<<
5690: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
56a0: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 TE_BUSY_SNAPSHOT
56b0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
56c0: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c TE_BUSY | (2<
56d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
56e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 ITE_CANTOPEN_NOT
56f0: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c EMPDIR (SQL
5700: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
5710: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5720: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 QLITE_CANTOPEN_I
5730: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53 SDIR (S
5740: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c QLITE_CANTOPEN |
5750: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
5760: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
5770: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 _FULLPATH
5780: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e (SQLITE_CANTOPEN
5790: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 | (3<<8)).#defi
57a0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 ne SQLITE_CANTOP
57b0: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 EN_CONVPATH
57c0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 (SQLITE_CANTOP
57d0: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 EN | (4<<8)).#de
57e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 fine SQLITE_CORR
57f0: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 UPT_VTAB
5800: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 (SQLITE_CORR
5810: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 UPT | (1<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
5830: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 DONLY_RECOVERY
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
5850: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a DONLY | (1<<8)).
5860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
5870: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b EADONLY_CANTLOCK
5880: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 (SQLITE_R
5890: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 EADONLY | (2<<8)
58a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
58b0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 _READONLY_ROLLBA
58c0: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 CK (SQLITE
58d0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c _READONLY | (3<<
58e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
58f0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f TE_READONLY_DBMO
5900: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 VED (SQLI
5910: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 TE_READONLY | (4
5920: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5930: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 LITE_ABORT_ROLLB
5940: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 ACK (SQ
5950: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c LITE_ABORT | (2<
5960: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5970: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 ITE_CONSTRAINT_C
5980: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c HECK (SQL
5990: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
59a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
59b0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
59c0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 NT_COMMITHOOK
59d0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
59e0: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 NT | (2<<8)).#de
59f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5a00: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 TRAINT_FOREIGNKE
5a10: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 Y (SQLITE_CONS
5a20: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 TRAINT | (3<<8))
5a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5a40: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 CONSTRAINT_FUNCT
5a50: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f ION (SQLITE_
5a60: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c CONSTRAINT | (4<
5a70: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5a80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e ITE_CONSTRAINT_N
5a90: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c OTNULL (SQL
5aa0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5ab0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (5<<8)).#define
5ac0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5ad0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 NT_PRIMARYKEY
5ae0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5af0: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 NT | (6<<8)).#de
5b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5b10: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 TRAINT_TRIGGER
5b20: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
5b30: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 TRAINT | (7<<8))
5b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5b50: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 CONSTRAINT_UNIQU
5b60: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f E (SQLITE_
5b70: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c CONSTRAINT | (8<
5b80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5b90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 ITE_CONSTRAINT_V
5ba0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c TAB (SQL
5bb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5bc0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (9<<8)).#define
5bd0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5be0: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 NT_ROWID
5bf0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5c00: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 NT |(10<<8)).#de
5c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 fine SQLITE_NOTI
5c20: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 CE_RECOVER_WAL
5c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 (SQLITE_NOTI
5c40: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 CE | (1<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 fine SQLITE_NOTI
5c60: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 CE_RECOVER_ROLLB
5c70: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 ACK (SQLITE_NOTI
5c80: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 CE | (2<<8)).#de
5c90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e fine SQLITE_WARN
5ca0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 ING_AUTOINDEX
5cb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e (SQLITE_WARN
5cc0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 ING | (1<<8)).#d
5cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 efine SQLITE_AUT
5ce0: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 H_USER
5cf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 (SQLITE_AUT
5d00: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a H | (1<<8))../*.
5d10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 ** CAPI3REF: Fla
5d20: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e gs For File Open
5d30: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a Operations.**.*
5d40: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 * These bit valu
5d50: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 es are intended
5d60: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a for use in the.*
5d70: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 * 3rd parameter
5d80: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
5d90: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 open_v2()] inter
5da0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 face and.** in t
5db0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
5dc0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
5dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 _vfs.xOpen] meth
5de0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 od..*/.#define S
5df0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
5e00: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 NLY 0x00
5e10: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 000001 /* Ok fo
5e20: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5e30: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5e40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
5e50: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 RITE 0x00
5e60: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 000002 /* Ok fo
5e70: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5e80: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5e90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
5ea0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 E 0x00
5eb0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 000004 /* Ok fo
5ec0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5ed0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5ee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
5ef0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 EONCLOSE 0x00
5f00: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 000008 /* VFS o
5f10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5f20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
5f30: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 SIVE 0x00
5f40: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 000010 /* VFS o
5f50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5f60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 QLITE_OPEN_AUTOP
5f70: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 ROXY 0x00
5f80: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 000020 /* VFS o
5f90: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5fa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 QLITE_OPEN_URI
5fb0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
5fc0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 000040 /* Ok fo
5fd0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5fe0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5ff0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 QLITE_OPEN_MEMOR
6000: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 Y 0x00
6010: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 000080 /* Ok fo
6020: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
6030: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
6050: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
6060: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 000100 /* VFS o
6070: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
6080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
6090: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
60a0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 000200 /* VFS o
60b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
60c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 QLITE_OPEN_TRANS
60d0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 IENT_DB 0x00
60e0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 000400 /* VFS o
60f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
6100: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
6110: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
6120: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 000800 /* VFS o
6130: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
6140: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
6150: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
6160: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 001000 /* VFS o
6170: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
6180: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
6190: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 URNAL 0x00
61a0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 002000 /* VFS o
61b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
61c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 QLITE_OPEN_MASTE
61d0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 R_JOURNAL 0x00
61e0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 004000 /* VFS o
61f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
6200: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
6210: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 EX 0x00
6220: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 008000 /* Ok fo
6230: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
6240: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
6250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
6260: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 UTEX 0x00
6270: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 010000 /* Ok fo
6280: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
6290: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
62a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
62b0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 DCACHE 0x00
62c0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 020000 /* Ok fo
62d0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
62e0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
62f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
6300: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 TECACHE 0x00
6310: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 040000 /* Ok fo
6320: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
6330: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
6340: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 QLITE_OPEN_WAL
6350: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6360: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 080000 /* VFS o
6370: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 nly */../* Reser
6380: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 ved:
6390: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
63a0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 0F00000 */../*.*
63b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 * CAPI3REF: Devi
63c0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 ce Characteristi
63d0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 cs.**.** The xDe
63e0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
63f0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 ics method of th
6400: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
6410: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 thods].** object
6420: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 returns an inte
6430: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 ger which is a v
6440: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a ector of these.*
6450: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 * bit values exp
6460: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 ressing I/O char
6470: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 acteristics of t
6480: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a he mass storage.
6490: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 ** device that h
64a0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 olds the file th
64b0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
64c0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 io_methods].** r
64d0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 efers to..**.**
64e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
64f0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
6500: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
6510: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
6520: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
6530: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
6540: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
6550: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
6560: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
6570: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
6580: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
6590: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
65a0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
65b0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
65c0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
65d0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
65e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
65f0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
6600: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
6610: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
6620: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
6630: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
6640: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
6650: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
6660: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
6670: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
6680: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
6690: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
66a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
66b0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
66c0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
66d0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
66e0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
66f0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
6700: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
6710: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 ite(). The SQLI
6720: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
6730: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f FE_OVERWRITE pro
6740: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
6750: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 .** after reboot
6760: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 following a cra
6770: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 sh or power loss
6780: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 , the only bytes
6790: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 in a.** file th
67a0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 at were written
67b0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 at the applicati
67c0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 on level might h
67d0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 ave changed.** a
67e0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 nd that adjacent
67f0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 bytes, even byt
6800: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 es within the sa
6810: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a me sector are.**
6820: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 guaranteed to b
6830: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 e unchanged. Th
6840: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 e SQLITE_IOCAP_U
6850: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f NDELETABLE_WHEN_
6860: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 OPEN.** flag ind
6870: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c icate that a fil
6880: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 e cannot be dele
6890: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 ted when open.
68a0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f The.** SQLITE_IO
68b0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c CAP_IMMUTABLE fl
68c0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 ag indicates tha
68d0: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e t the file is on
68e0: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 .** read-only me
68f0: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 dia and cannot b
6900: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 e changed even b
6910: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 y processes with
6920: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 .** elevated pri
6930: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 vileges..*/.#def
6940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6950: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 _ATOMIC
6960: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6970: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 01.#define SQLIT
6980: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
6990: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 2 0
69a0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e x00000002.#defin
69b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
69c0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 TOMIC1K
69d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
69e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
69f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 IOCAP_ATOMIC2K
6a00: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6a10: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 0000008.#define
6a20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6a30: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 MIC4K
6a40: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 0x00000010.#
6a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6a60: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 CAP_ATOMIC8K
6a70: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6a80: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 00020.#define SQ
6a90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6aa0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 C16K
6ab0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 0x00000040.#de
6ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6ad0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 P_ATOMIC32K
6ae0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6af0: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 080.#define SQLI
6b00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 TE_IOCAP_ATOMIC6
6b10: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 4K
6b20: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 0x00000100.#defi
6b30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6b40: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 SAFE_APPEND
6b50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 0x0000020
6b60: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
6b70: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
6b80: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 L 0x
6b90: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 00000400.#define
6ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e SQLITE_IOCAP_UN
6bb0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f DELETABLE_WHEN_O
6bc0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a PEN 0x00000800.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6be0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f OCAP_POWERSAFE_O
6bf0: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 VERWRITE 0x00
6c00: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 001000.#define S
6c10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 QLITE_IOCAP_IMMU
6c20: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 TABLE
6c30: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 0x00002000../
6c40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
6c50: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 ile Locking Leve
6c60: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 ls.**.** SQLite
6c70: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 uses one of thes
6c80: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
6c90: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a as the second.*
6ca0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 * argument to ca
6cb0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 lls it makes to
6cc0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 the xLock() and
6cd0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 xUnlock() method
6ce0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 s.** of an [sqli
6cf0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
6d00: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 object..*/.#defi
6d10: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e ne SQLITE_LOCK_N
6d20: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 ONE 0.#
6d30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
6d40: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 CK_SHARED
6d50: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
6d60: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 E_LOCK_RESERVED
6d70: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
6d80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
6d90: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 NG 3.#defi
6da0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 ne SQLITE_LOCK_E
6db0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a XCLUSIVE 4..
6dc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
6dd0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 Synchronization
6de0: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a Type Flags.**.**
6df0: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 When SQLite inv
6e00: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 okes the xSync()
6e10: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a method of an.**
6e20: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
6e30: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 hods] object it
6e40: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 uses a combinati
6e50: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 on of.** these i
6e60: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 nteger values as
6e70: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
6e80: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e ment..**.** When
6e90: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 the SQLITE_SYNC
6ea0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 _DATAONLY flag i
6eb0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 s used, it means
6ec0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e that the.** syn
6ed0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 c operation only
6ee0: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 needs to flush
6ef0: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f data to mass sto
6f00: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 rage. Inode.**
6f10: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 information need
6f20: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e not be flushed.
6f30: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f If the lower fo
6f40: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 ur bits of the f
6f50: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c lag.** equal SQL
6f60: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c ITE_SYNC_NORMAL,
6f70: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 that means to u
6f80: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 se normal fsync(
6f90: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 ) semantics..**
6fa0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 If the lower fou
6fb0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c r bits equal SQL
6fc0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 ITE_SYNC_FULL, t
6fd0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 hat means.** to
6fe0: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 use Mac OS X sty
6ff0: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 le fullsync inst
7000: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a ead of fsync()..
7010: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e **.** Do not con
7020: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f fuse the SQLITE_
7030: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
7040: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
7050: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 flags.** with t
7060: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 he [PRAGMA synch
7070: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 ronous]=NORMAL a
7080: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 nd [PRAGMA synch
7090: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 ronous]=FULL.**
70a0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b settings. The [
70b0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 synchronous prag
70c0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 ma] determines w
70d0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 hen calls to the
70e0: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 .** xSync VFS me
70f0: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 thod occur and a
7100: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 pplies uniformly
7110: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 across all plat
7120: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 forms..** The SQ
7130: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
7140: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 and SQLITE_SYNC
7150: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 _FULL flags dete
7160: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 rmine how.** ene
7170: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f rgetic or rigoro
7180: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 us or forceful t
7190: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f he sync operatio
71a0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e ns are and.** on
71b0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 ly make a differ
71c0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 ence on Mac OSX
71d0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 for the default
71e0: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 SQLite code..**
71f0: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 (Third-party VFS
7200: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
7210: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 might also make
7220: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e the distinction
7230: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 .** between SQLI
7240: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 TE_SYNC_NORMAL a
7250: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 nd SQLITE_SYNC_F
7260: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 ULL, but among t
7270: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 he.** operating
7280: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 systems natively
7290: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 supported by SQ
72a0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f Lite, only Mac O
72b0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 SX.** cares abou
72c0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 t the difference
72d0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 .).*/.#define SQ
72e0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
72f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 0x00002.
7300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
7310: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 YNC_FULL
7320: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 0x00003.#defin
7330: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
7340: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 TAONLY 0x00
7350: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 010../*.** CAPI3
7360: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
7370: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 e Open File Hand
7380: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c le.**.** An [sql
7390: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
73a0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 t represents an
73b0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 open file in the
73c0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 .** [sqlite3_vf
73d0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 s | OS interface
73e0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 layer]. Indivi
73f0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 dual OS interfac
7400: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
7410: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e ions will.** wan
7420: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 t to subclass th
7430: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 is object by app
7440: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 ending additiona
7450: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 l fields.** for
7460: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 their own use.
7470: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 The pMethods ent
7480: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ry is a pointer
7490: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 to an.** [sqlite
74a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
74b0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
74c0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 s methods for pe
74d0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 rforming.** I/O
74e0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 operations on th
74f0: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a e open file..*/.
7500: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
7510: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 qlite3_file sqli
7520: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 te3_file;.struct
7530: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a sqlite3_file {.
7540: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 const struct s
7550: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
7560: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a s *pMethods; /*
7570: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 Methods for an
7580: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a open file */.};.
7590: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
75a0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 OS Interface Fi
75b0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f le Virtual Metho
75c0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 ds Object.**.**
75d0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 Every file opene
75e0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
75f0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 3_vfs.xOpen] met
7600: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e hod populates an
7610: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
7620: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d e] object (or, m
7630: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 ore commonly, a
7640: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a subclass of the.
7650: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
7660: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 ] object) with a
7670: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
7680: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
7690: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 object..** This
76a0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
76b0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 he methods used
76c0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
76d0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a us operations.**
76e0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 against the ope
76f0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 n file represent
7700: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
7710: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e e3_file] object.
7720: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 .**.** If the [s
7730: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
7740: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 ] method sets th
7750: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
7760: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 Methods element
7770: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c .** to a non-NUL
7780: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
7790: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d the sqlite3_io_m
77a0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 ethods.xClose me
77b0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 thod.** may be i
77c0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 nvoked even if t
77d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
77e0: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 xOpen] reported
77f0: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 that it failed.
7800: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 The.** only way
7810: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 to prevent a ca
7820: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c ll to xClose fol
7830: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 lowing a failed
7840: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
7850: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 en].** is for th
7860: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
7870: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 Open] to set the
7880: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
7890: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a ethods element.*
78a0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a * to NULL..**.**
78b0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d The flags argum
78c0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 ent to xSync may
78d0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 be one of [SQLI
78e0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 TE_SYNC_NORMAL]
78f0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 or.** [SQLITE_SY
7900: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 NC_FULL]. The f
7910: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 irst choice is t
7920: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 he normal fsync(
7930: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 )..** The second
7940: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 choice is a Mac
7950: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c OS X style full
7960: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 sync. The [SQLI
7970: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
7980: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 ].** flag may be
7990: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 ORed in to indi
79a0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 cate that only t
79b0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 he data of the f
79c0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 ile.** and not i
79d0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 ts inode needs t
79e0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a o be synced..**.
79f0: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 ** The integer v
7a00: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 alues to xLock()
7a10: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 and xUnlock() a
7a20: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c re one of.** <ul
7a30: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
7a40: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a E_LOCK_NONE],.**
7a50: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
7a60: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c CK_SHARED],.** <
7a70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
7a80: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c _RESERVED],.** <
7a90: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
7aa0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a _PENDING], or.**
7ab0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
7ac0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a CK_EXCLUSIVE]..*
7ad0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b * </ul>.** xLock
7ae0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 () increases the
7af0: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 lock. xUnlock()
7b00: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c decreases the l
7b10: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 ock..** The xChe
7b20: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 ckReservedLock()
7b30: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 method checks w
7b40: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 hether any datab
7b50: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a ase connection,.
7b60: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 ** either in thi
7b70: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 s process or in
7b80: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 some other proce
7b90: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 ss, is holding a
7ba0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 RESERVED,.** PE
7bb0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 NDING, or EXCLUS
7bc0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 IVE lock on the
7bd0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e file. It return
7be0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 s true.** if suc
7bf0: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 h a lock exists
7c00: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 and false otherw
7c10: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ise..**.** The x
7c20: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 FileControl() me
7c30: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 thod is a generi
7c40: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 c interface that
7c50: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a allows custom.*
7c60: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 * VFS implementa
7c70: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c tions to directl
7c80: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 y control an ope
7c90: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 n file using the
7ca0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
7cb0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 e_control()] int
7cc0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 erface. The sec
7cd0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e ond "op" argumen
7ce0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 t is an.** integ
7cf0: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 er opcode. The
7d00: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
7d10: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e s a generic poin
7d20: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a ter intended to.
7d30: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 ** point to a st
7d40: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 ructure that may
7d50: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e contain argumen
7d60: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 ts or space in w
7d70: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 hich to.** write
7d80: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 return values.
7d90: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 Potential uses
7da0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c for xFileControl
7db0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 () might be.** f
7dc0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 unctions to enab
7dd0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b le blocking lock
7de0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c s with timeouts,
7df0: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a to change the.*
7e00: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 * locking strate
7e10: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 gy (for example
7e20: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 to use dot-file
7e30: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 locks), to inqui
7e40: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 re.** about the
7e50: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b status of a lock
7e60: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 , or to break st
7e70: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 ale locks. The
7e80: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 SQLite.** core r
7e90: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f eserves all opco
7ea0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 des less than 10
7eb0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 0 for its own us
7ec0: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f e..** A [file co
7ed0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 ntrol opcodes |
7ee0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d list of opcodes]
7ef0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 less than 100 i
7f00: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 s available..**
7f10: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
7f20: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f t define a custo
7f30: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d m xFileControl m
7f40: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 ethod should use
7f50: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 opcodes.** grea
7f60: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 ter than 100 to
7f70: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e avoid conflicts.
7f80: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 VFS implementa
7f90: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 tions should.**
7fa0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e return [SQLITE_N
7fb0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c OTFOUND] for fil
7fc0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 e control opcode
7fd0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e s that they do n
7fe0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e ot.** recognize.
7ff0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 .**.** The xSect
8000: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 orSize() method
8010: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 returns the sect
8020: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a or size of the.*
8030: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e * device that un
8040: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 derlies the file
8050: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 . The sector si
8060: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e ze is the.** min
8070: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 imum write that
8080: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 can be performed
8090: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 without disturb
80a0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 ing.** other byt
80b0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 es in the file.
80c0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 The xDeviceChar
80d0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a acteristics().**
80e0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
80f0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 a bit vector des
8100: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 cribing behavior
8110: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 s of the.** unde
8120: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a rlying device:.*
8130: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
8140: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
8150: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 ATOMIC].** <li>
8160: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
8170: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e OMIC512].** <li>
8180: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
8190: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC1K].** <li>
81a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
81b0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC2K].** <li>
81c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
81d0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC4K].** <li>
81e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
81f0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC8K].** <li>
8200: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
8210: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC16K].** <li
8220: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
8230: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c ATOMIC32K].** <l
8240: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
8250: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c _ATOMIC64K].** <
8260: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
8270: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a P_SAFE_APPEND].*
8280: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
8290: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d OCAP_SEQUENTIAL]
82a0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
82b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
82c0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
82d0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
82e0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
82f0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
8300: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
8310: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
8320: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
8330: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
8340: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
8350: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
8360: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
8370: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
8380: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
8390: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
83a0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
83b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
83c0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
83d0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
83e0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
83f0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
8400: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
8410: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
8420: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
8430: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
8440: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
8450: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
8460: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
8470: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
8480: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
8490: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
84a0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
84b0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
84c0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
84d0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
84e0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ite()..**.** If
84f0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 xRead() returns
8500: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
8510: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 RT_READ it must
8520: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 also fill.** in
8530: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 the unread porti
8540: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 ons of the buffe
8550: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 r with zeros. A
8560: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 VFS that.** fai
8570: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 ls to zero-fill
8580: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 short reads migh
8590: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 t seem to work.
85a0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 However,.** fai
85b0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c lure to zero-fil
85c0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 l short reads wi
85d0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 ll eventually le
85e0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 ad to.** databas
85f0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f e corruption..*/
8600: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
8610: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
8620: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ds sqlite3_io_me
8630: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
8640: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
8650: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f {. int iVersio
8660: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 n;. int (*xClos
8670: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
8680: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 );. int (*xRead
8690: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
86a0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 void*, int iAmt
86b0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
86c0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a iOfst);. int (*
86d0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f xWrite)(sqlite3_
86e0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 file*, const voi
86f0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 d*, int iAmt, sq
8700: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 lite3_int64 iOfs
8710: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 t);. int (*xTru
8720: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 ncate)(sqlite3_f
8730: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
8740: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 t64 size);. int
8750: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 (*xSync)(sqlite
8760: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 3_file*, int fla
8770: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 gs);. int (*xFi
8780: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f leSize)(sqlite3_
8790: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
87a0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 nt64 *pSize);.
87b0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c int (*xLock)(sql
87c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 ite3_file*, int)
87d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 ;. int (*xUnloc
87e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
87f0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a , int);. int (*
8800: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f xCheckReservedLo
8810: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
8820: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 *, int *pResOut)
8830: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 ;. int (*xFileC
8840: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f ontrol)(sqlite3_
8850: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 file*, int op, v
8860: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e oid *pArg);. in
8870: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 t (*xSectorSize)
8880: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
8890: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 . int (*xDevice
88a0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 Characteristics)
88b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
88c0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 . /* Methods ab
88d0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f ove are valid fo
88e0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 r version 1 */.
88f0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 int (*xShmMap)(
8900: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
8910: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a nt iPg, int pgsz
8920: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 , int, void vola
8930: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 tile**);. int (
8940: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 *xShmLock)(sqlit
8950: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 e3_file*, int of
8960: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 fset, int n, int
8970: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 flags);. void
8980: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 (*xShmBarrier)(s
8990: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
89a0: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 int (*xShmUnmap
89b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
89c0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 int deleteFlag)
89d0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 ;. /* Methods a
89e0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 bove are valid f
89f0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a or version 2 */.
8a00: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 int (*xFetch)(
8a10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
8a20: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
8a30: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f st, int iAmt, vo
8a40: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 id **pp);. int
8a50: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 (*xUnfetch)(sqli
8a60: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
8a70: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 e3_int64 iOfst,
8a80: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d void *p);. /* M
8a90: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
8aa0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 valid for versi
8ab0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 on 3 */. /* Add
8ac0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 itional methods
8ad0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
8ae0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
8af0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
8b00: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 I3REF: Standard
8b10: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 File Control Opc
8b20: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 odes.** KEYWORDS
8b30: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 : {file control
8b40: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 opcodes} {file c
8b50: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a ontrol opcode}.*
8b60: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 *.** These integ
8b70: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 er constants are
8b80: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 opcodes for the
8b90: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
8ba0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b thod.** of the [
8bb0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
8bc0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 ds] object and f
8bd0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f or the [sqlite3_
8be0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a file_control()].
8bf0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a ** interface..**
8c00: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
8c10: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c [[SQLITE_FCNTL_L
8c20: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 OCKSTATE]].** Th
8c30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
8c40: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 LOCKSTATE] opcod
8c50: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 e is used for de
8c60: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a bugging. This.*
8c70: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 * opcode causes
8c80: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
8c90: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 method to write
8ca0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 the current sta
8cb0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 te of.** the loc
8cc0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 k (one of [SQLIT
8cd0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 E_LOCK_NONE], [S
8ce0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
8cf0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c D],.** [SQLITE_L
8d00: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b OCK_RESERVED], [
8d10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
8d20: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 ING], or [SQLITE
8d30: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d _LOCK_EXCLUSIVE]
8d40: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 ).** into an int
8d50: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 eger that the pA
8d60: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e rg argument poin
8d70: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 ts to. This capa
8d80: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 bility.** is use
8d90: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 d during testing
8da0: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 and is only ava
8db0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 ilable when the
8dc0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 SQLITE_TEST.** c
8dd0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
8de0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a on is used..**.*
8df0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
8e00: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d CNTL_SIZE_HINT]]
8e10: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
8e20: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d FCNTL_SIZE_HINT]
8e30: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
8e40: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 by SQLite to giv
8e50: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 e the VFS.** lay
8e60: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 er a hint of how
8e70: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 large the datab
8e80: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 ase file will gr
8e90: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 ow to be during
8ea0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 the.** current t
8eb0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 ransaction. Thi
8ec0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 s hint is not gu
8ed0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 aranteed to be a
8ee0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a ccurate but it.*
8ef0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 * is often close
8f00: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e . The underlyin
8f10: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f g VFS might choo
8f20: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 se to preallocat
8f30: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 e database.** fi
8f40: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f le space based o
8f50: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f n this hint in o
8f60: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 rder to help wri
8f70: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 tes to the datab
8f80: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 ase.** file run
8f90: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c faster..**.** <l
8fa0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
8fb0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a _CHUNK_SIZE]].**
8fc0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
8fd0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f TL_CHUNK_SIZE] o
8fe0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
8ff0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 request that th
9000: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 e VFS.** extends
9010: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 and truncates t
9020: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
9030: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 in chunks of a
9040: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a size specified.*
9050: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 * by the user. T
9060: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
9070: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 nt to [sqlite3_f
9080: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 ile_control()] s
9090: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 hould .** point
90a0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 to an integer (t
90b0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e ype int) contain
90c0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e ing the new chun
90d0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a k-size to use.**
90e0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 for the nominat
90f0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c ed database. All
9100: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 ocating database
9110: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c file space in l
9120: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 arge.** chunks (
9130: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d say 1MB at a tim
9140: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 e), may reduce f
9150: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d ile-system fragm
9160: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 entation and.**
9170: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 improve performa
9180: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 nce on some syst
9190: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ems..**.** <li>[
91a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 [SQLITE_FCNTL_FI
91b0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 LE_POINTER]].**
91c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
91d0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 L_FILE_POINTER]
91e0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
91f0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 o obtain a point
9200: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 er.** to the [sq
9210: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
9220: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ct associated wi
9230: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 th a particular
9240: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
9250: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 ection. See the
9260: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
9270: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 ontrol()] docume
9280: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 ntation for.** a
9290: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
92a0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ation..**.** <li
92b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
92c0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a SYNC_OMITTED]].*
92d0: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 * No longer in u
92e0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b se..**.** <li>[[
92f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e SQLITE_FCNTL_SYN
9300: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 C]].** The [SQLI
9310: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f TE_FCNTL_SYNC] o
9320: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 pcode is generat
9330: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 ed internally by
9340: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 SQLite and.** s
9350: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 ent to the VFS i
9360: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 mmediately befor
9370: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 e the xSync meth
9380: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e od is invoked on
9390: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 a.** database f
93a0: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 ile descriptor.
93b0: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 Or, if the xSync
93c0: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 method is not i
93d0: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 nvoked .** becau
93e0: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 se the user has
93f0: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 configured SQLit
9400: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 e with .** [PRAG
9410: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c MA synchronous |
9420: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e PRAGMA synchron
9430: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 ous=OFF] it is i
9440: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 nvoked in place
9450: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 .** of the xSync
9460: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 method. In most
9470: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e cases, the poin
9480: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 ter argument pas
9490: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 sed with.** this
94a0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 file-control is
94b0: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 NULL. However,
94c0: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 if the database
94d0: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 file is being sy
94e0: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 nced.** as part
94f0: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 of a multi-datab
9500: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 ase commit, the
9510: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 argument points
9520: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 to a nul-termina
9530: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f ted.** string co
9540: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 ntaining the tra
9550: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 nsactions master
9560: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 -journal file na
9570: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a me. VFSes that .
9580: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 ** do not need t
9590: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c his signal shoul
95a0: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 d silently ignor
95b0: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 e this opcode. A
95c0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 pplications .**
95d0: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 should not call
95e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
95f0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 ntrol()] with th
9600: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 is opcode as doi
9610: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 ng so may .** di
9620: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 srupt the operat
9630: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 ion of the speci
9640: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 alized VFSes tha
9650: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e t do require it.
9660: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 .**.** <li>[[S
9670: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d QLITE_FCNTL_COMM
9680: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a IT_PHASETWO]].**
9690: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
96a0: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 TL_COMMIT_PHASET
96b0: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 WO] opcode is ge
96c0: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c nerated internal
96d0: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ly by SQLite.**
96e0: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 and sent to the
96f0: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e VFS after a tran
9700: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e saction has been
9710: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 committed immed
9720: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 iately.** but be
9730: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 fore the databas
9740: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 e is unlocked. V
9750: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 FSes that do not
9760: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 need this signa
9770: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 l.** should sile
9780: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 ntly ignore this
9790: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 opcode. Applica
97a0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 tions should not
97b0: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 call.** [sqlite
97c0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
97d0: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f ] with this opco
97e0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d de as doing so m
97f0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a ay disrupt the .
9800: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 ** operation of
9810: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 the specialized
9820: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 VFSes that do re
9830: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a quire it. .**.*
9840: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
9850: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 CNTL_WIN32_AV_RE
9860: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 TRY]].** ^The [S
9870: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
9880: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 2_AV_RETRY] opco
9890: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f de is used to co
98a0: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 nfigure automati
98b0: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 c.** retry count
98c0: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 s and intervals
98d0: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b for certain disk
98e0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 I/O operations
98f0: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f for the.** windo
9900: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 ws [VFS] in orde
9910: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 r to provide rob
9920: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 ustness in the p
9930: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e resence of.** an
9940: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d ti-virus program
9950: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 s. By default,
9960: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 the windows VFS
9970: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 will retry file
9980: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 read,.** file wr
9990: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 ite, and file de
99a0: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 lete operations
99b0: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 up to 10 times,
99c0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 with a delay.**
99d0: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e of 25 millisecon
99e0: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 ds before the fi
99f0: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 rst retry and wi
9a00: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 th the delay inc
9a10: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e reasing.** by an
9a20: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d additional 25 m
9a30: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 illiseconds with
9a40: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 each subsequent
9a50: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a retry. This.**
9a60: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 opcode allows t
9a70: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 hese two values
9a80: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 (10 retries and
9a90: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 25 milliseconds
9aa0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 of delay).** to
9ab0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 be adjusted. Th
9ac0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 e values are cha
9ad0: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 nged for all dat
9ae0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
9af0: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 s.** within the
9b00: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 same process. T
9b10: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 he argument is a
9b20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 pointer to an a
9b30: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 rray of two.** i
9b40: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 ntegers where th
9b50: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 e first integer
9b60: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 i the new retry
9b70: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 count and the se
9b80: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 cond.** integer
9b90: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 is the delay. I
9ba0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 f either integer
9bb0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
9bc0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a en the setting.*
9bd0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 * is not changed
9be0: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 but instead the
9bf0: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 prior value of
9c00: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 that setting is
9c10: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 written.** into
9c20: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c the array entry,
9c30: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 allowing the cu
9c40: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 rrent retry sett
9c50: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e ings to be.** in
9c60: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 terrogated. The
9c70: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 zDbName paramet
9c80: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a er is ignored..*
9c90: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9ca0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f E_FCNTL_PERSIST_
9cb0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 WAL]].** ^The [S
9cc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 QLITE_FCNTL_PERS
9cd0: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 IST_WAL] opcode
9ce0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f is used to set o
9cf0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 r query the.** p
9d00: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c ersistent [WAL |
9d10: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 Write Ahead Log
9d20: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 ] setting. By d
9d30: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 efault, the auxi
9d40: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 liary.** write a
9d50: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 head log and sha
9d60: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 red memory files
9d70: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 used for transa
9d80: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a ction control.**
9d90: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c are automatical
9da0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 ly deleted when
9db0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 the latest conne
9dc0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 ction to the dat
9dd0: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e abase.** closes.
9de0: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 Setting persis
9df0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 tent WAL mode ca
9e00: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 uses those files
9e10: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 to persist afte
9e20: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 r.** close. Per
9e30: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 sisting the file
9e40: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e s is useful when
9e50: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 other processes
9e60: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 that do not.**
9e70: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 have write permi
9e80: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 ssion on the dir
9e90: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e ectory containin
9ea0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 g the database f
9eb0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 ile want.** to r
9ec0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 ead the database
9ed0: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 file, as the WA
9ee0: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d L and shared mem
9ef0: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 ory files must e
9f00: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 xist.** in order
9f10: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 for the databas
9f20: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 e to be readable
9f30: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 . The fourth pa
9f40: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 rameter to.** [s
9f50: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
9f60: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 rol()] for this
9f70: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 opcode should be
9f80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
9f90: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 integer..** Tha
9fa0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 t integer is 0 t
9fb0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 o disable persis
9fc0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 tent WAL mode or
9fd0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 1 to enable per
9fe0: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d sistent.** WAL m
9ff0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 ode. If the int
a000: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e eger is -1, then
a010: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 it is overwritt
a020: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 en with the curr
a030: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 ent.** WAL persi
a040: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a stence setting..
a050: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
a060: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 TE_FCNTL_POWERSA
a070: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a FE_OVERWRITE]].*
a080: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
a090: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f CNTL_POWERSAFE_O
a0a0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 VERWRITE] opcode
a0b0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 is used to set
a0c0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 or query the.**
a0d0: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 persistent "powe
a0e0: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 rsafe-overwrite"
a0f0: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 or "PSOW" setti
a100: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 ng. The PSOW se
a110: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 tting.** determi
a120: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f nes the [SQLITE_
a130: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f IOCAP_POWERSAFE_
a140: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f OVERWRITE] bit o
a150: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 f the.** xDevice
a160: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 Characteristics
a170: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 methods. The fou
a180: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
a190: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
a1a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 e_control()] for
a1b0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f this opcode sho
a1c0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 uld be a pointer
a1d0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a to an integer..
a1e0: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 ** That integer
a1f0: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
a200: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 zero-damage mode
a210: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 or 1 to enable
a220: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d zero-damage.** m
a230: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 ode. If the int
a240: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e eger is -1, then
a250: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 it is overwritt
a260: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 en with the curr
a270: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 ent.** zero-dama
a280: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e ge mode setting.
a290: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
a2a0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 ITE_FCNTL_OVERWR
a2b0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 ITE]].** ^The [S
a2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
a2d0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 WRITE] opcode is
a2e0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 invoked by SQLi
a2f0: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 te after opening
a300: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e .** a write tran
a310: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 saction to indic
a320: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 ate that, unless
a330: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 it is rolled ba
a340: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 ck for some.** r
a350: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 eason, the entir
a360: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
a370: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 will be overwrit
a380: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 ten by the curre
a390: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 nt .** transacti
a3a0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 on. This is used
a3b0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 by VACUUM opera
a3c0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 tions..**.** <li
a3d0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
a3e0: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 VFSNAME]].** ^Th
a3f0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
a400: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 VFSNAME] opcode
a410: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
a420: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 btain the names
a430: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 of.** all [VFSes
a440: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 ] in the VFS sta
a450: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 ck. The names a
a460: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 re of all VFS sh
a470: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 ims and the.** f
a480: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 inal bottom-leve
a490: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 l VFS are writte
a4a0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 n into memory ob
a4b0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 tained from .**
a4c0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
a4d0: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c )] and the resul
a4e0: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 t is stored in t
a4f0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c he char* variabl
a500: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f e.** that the fo
a510: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f urth parameter o
a520: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f f [sqlite3_file_
a530: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 control()] point
a540: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c s to..** The cal
a550: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ler is responsib
a560: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 le for freeing t
a570: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 he memory when d
a580: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a one. As with.**
a590: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f all file-contro
a5a0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 l actions, there
a5b0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 is no guarantee
a5c0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 that this will
a5d0: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 actually.** do a
a5e0: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 nything. Caller
a5f0: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c s should initial
a600: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 ize the char* va
a610: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c riable to a NULL
a620: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 .** pointer in c
a630: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f ase this file-co
a640: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 ntrol is not imp
a650: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 lemented. This
a660: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 file-control.**
a670: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 is intended for
a680: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f diagnostic use o
a690: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b nly..**.** <li>[
a6a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 [SQLITE_FCNTL_VF
a6b0: 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e S_POINTER]].** ^
a6c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
a6d0: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f L_VFS_POINTER] o
a6e0: 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f pcode finds a po
a6f0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 inter to the top
a700: 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 -level.** [VFSes
a710: 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 ] currently in u
a720: 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d se. ^(The argum
a730: 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 ent X in.** sqli
a740: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
a750: 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c (db,SQLITE_FCNTL
a760: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20 _VFS_POINTER,X)
a770: 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79 must be.** of ty
a780: 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73 pe "[sqlite3_vfs
a790: 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63 ] **". This opc
a7a0: 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58 odes will set *X
a7b0: 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72 .** to a pointer
a7c0: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 to the top-leve
a7d0: 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 l VFS.)^.** ^Whe
a7e0: 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74 n there are mult
a7f0: 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69 iple VFS shims i
a800: 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69 n the stack, thi
a810: 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74 s opcode finds t
a820: 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74 he.** upper-most
a830: 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a shim only..**.*
a840: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
a850: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a CNTL_PRAGMA]].**
a860: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 ^Whenever a [PR
a870: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 AGMA] statement
a880: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 is parsed, an [S
a890: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
a8a0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e MA] .** file con
a8b0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 trol is sent to
a8c0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 the open [sqlite
a8d0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 3_file] object c
a8e0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 orresponding.**
a8f0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 to the database
a900: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 file to which th
a910: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 e pragma stateme
a920: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 nt refers. ^The
a930: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 argument.** to t
a940: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
a950: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
a960: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 ntrol is an arra
a970: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 y of.** pointers
a980: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 to strings (cha
a990: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 r**) in which th
a9a0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 e second element
a9b0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a of the array.**
a9c0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
a9d0: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 the pragma and t
a9e0: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 he third element
a9f0: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 is the argument
aa00: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d to the.** pragm
aa10: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 a or NULL if the
aa20: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 pragma has no a
aa30: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 rgument. ^The h
aa40: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a andler for an.**
aa50: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
aa60: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 RAGMA] file cont
aa70: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c rol can optional
aa80: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 ly make the firs
aa90: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 t element.** of
aaa0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d the char** argum
aab0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 ent point to a s
aac0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 tring obtained f
aad0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 rom [sqlite3_mpr
aae0: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 intf()].** or th
aaf0: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 e equivalent and
ab00: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c that string wil
ab10: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 l become the res
ab20: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d ult of the pragm
ab30: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f a or.** the erro
ab40: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 r message if the
ab50: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e pragma fails. ^
ab60: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 If the.** [SQLIT
ab70: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
ab80: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 file control ret
ab90: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 urns [SQLITE_NOT
aba0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 FOUND], then nor
abb0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d mal .** [PRAGMA]
abc0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 processing cont
abd0: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 inues. ^If the
abe0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
abf0: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f AGMA].** file co
ac00: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 ntrol returns [S
ac10: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 QLITE_OK], then
ac20: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d the parser assum
ac30: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 es that the.** V
ac40: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 FS has handled t
ac50: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 he PRAGMA itself
ac60: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 and the parser
ac70: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f generates a no-o
ac80: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 p.** prepared st
ac90: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c atement if resul
aca0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c t string is NULL
acb0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e , or that return
acc0: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 s a copy.** of t
acd0: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 he result string
ace0: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 if the string i
acf0: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e s non-NULL..** ^
ad00: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 If the [SQLITE_F
ad10: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
ad20: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e e control return
ad30: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 s.** any result
ad40: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 code other than
ad50: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b [SQLITE_OK] or [
ad60: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d SQLITE_NOTFOUND]
ad70: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 , that means.**
ad80: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 that the VFS enc
ad90: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f ountered an erro
ada0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 r while handling
adb0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e the [PRAGMA] an
adc0: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 d the.** compila
add0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 tion of the PRAG
ade0: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e MA fails with an
adf0: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 error. ^The [S
ae00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
ae10: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 MA].** file cont
ae20: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 rol occurs at th
ae30: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 e beginning of p
ae40: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 ragma statement
ae50: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a analysis and so.
ae60: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f ** it is able to
ae70: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d override built-
ae80: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 in [PRAGMA] stat
ae90: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ements..**.** <l
aea0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
aeb0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a _BUSYHANDLER]].*
aec0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
aed0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 CNTL_BUSYHANDLER
aee0: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f ].** file-contro
aef0: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 l may be invoked
af00: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 by SQLite on th
af10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
af20: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c handle.** shortl
af30: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 y after it is op
af40: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f ened in order to
af50: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f provide a custo
af60: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 m VFS with acces
af70: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e s.** to the conn
af80: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e ections busy-han
af90: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 dler callback. T
afa0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f he argument is o
afb0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 f type (void **)
afc0: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f .** - an array o
afd0: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 f two (void *) v
afe0: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 alues. The first
aff0: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c (void *) actual
b000: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 ly points.** to
b010: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 a function of ty
b020: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 pe (int (*)(void
b030: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 *)). In order t
b040: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e o invoke the con
b050: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 nections.** busy
b060: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 -handler, this f
b070: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 unction should b
b080: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 e invoked with t
b090: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 he second (void
b0a0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 *) in.** the arr
b0b0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 ay as the only a
b0c0: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 rgument. If it r
b0d0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
b0e0: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 then the operat
b0f0: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 ion.** should be
b100: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 retried. If it
b110: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 returns zero, th
b120: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f e custom VFS sho
b130: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a uld abandon the.
b140: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 ** current opera
b150: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e tion..**.** <li>
b160: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 [[SQLITE_FCNTL_T
b170: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a EMPFILENAME]].**
b180: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 ^Application ca
b190: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 n invoke the [SQ
b1a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 LITE_FCNTL_TEMPF
b1b0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f ILENAME] file-co
b1c0: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 ntrol.** to have
b1d0: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 SQLite generate
b1e0: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 a.** temporary
b1f0: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 filename using t
b200: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 he same algorith
b210: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 m that is follow
b220: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a ed to generate.*
b230: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 * temporary file
b240: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 names for TEMP t
b250: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 ables and other
b260: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 internal uses.
b270: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 The.** argument
b280: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 should be a char
b290: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 ** which will be
b2a0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
b2b0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 filename.** wri
b2c0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 tten into memory
b2d0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
b2e0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
b2f0: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 ]. The caller s
b300: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 hould.** invoke
b310: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
b320: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 on the result t
b330: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 o avoid a memory
b340: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 leak..**.** <li
b350: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
b360: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 MMAP_SIZE]].** T
b370: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
b380: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 _MMAP_SIZE] file
b390: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 control is used
b3a0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 to query or set
b3b0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 the.** maximum
b3c0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
b3d0: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 that will be use
b3e0: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 d for memory-map
b3f0: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 ped I/O..** The
b400: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
b410: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 inter to a value
b420: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 of type sqlite3
b430: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 _int64 that.** i
b440: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 s an advisory ma
b450: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
b460: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c bytes in the fil
b470: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e e to memory map.
b480: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 The.** pointer
b490: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 is overwritten
b4a0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c with the old val
b4b0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 ue. The limit i
b4c0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 s not changed if
b4d0: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 .** the value or
b4e0: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 iginally pointed
b4f0: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c to is negative,
b500: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 and so the curr
b510: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 ent limit .** ca
b520: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 n be queried by
b530: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 passing in a poi
b540: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 nter to a negati
b550: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 ve number. This
b560: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c .** file-control
b570: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 is used interna
b580: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 lly to implement
b590: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 [PRAGMA mmap_si
b5a0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ze]..**.** <li>[
b5b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 [SQLITE_FCNTL_TR
b5c0: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 ACE]].** The [SQ
b5d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 LITE_FCNTL_TRACE
b5e0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 ] file control p
b5f0: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 rovides advisory
b600: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
b610: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 to the VFS about
b620: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 what the higher
b630: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 layers of the S
b640: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 QLite stack are
b650: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 doing..** This f
b660: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 ile control is u
b670: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 sed by some VFS
b680: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 activity tracing
b690: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 [shims]..** The
b6a0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a argument is a z
b6b0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
b6c0: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c tring. Higher l
b6d0: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 ayers in the.**
b6e0: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 SQLite stack may
b6f0: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e generate instan
b700: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 ces of this file
b710: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 control if.** t
b720: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 he [SQLITE_USE_F
b730: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 CNTL_TRACE] comp
b740: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
b750: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a is enabled..**.*
b760: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
b770: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d CNTL_HAS_MOVED]]
b780: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
b790: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d FCNTL_HAS_MOVED]
b7a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e file control in
b7b0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 terprets its arg
b7c0: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f ument as a.** po
b7d0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
b7e0: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 ger and it write
b7f0: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f s a boolean into
b800: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 that integer de
b810: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 pending.** on wh
b820: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
b830: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 file has been r
b840: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f enamed, moved, o
b850: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 r deleted since
b860: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 it.** was first
b870: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c opened..**.** <l
b880: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
b890: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c _WIN32_SET_HANDL
b8a0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 E]].** The [SQLI
b8b0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 TE_FCNTL_WIN32_S
b8c0: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 ET_HANDLE] opcod
b8d0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 e is used for de
b8e0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a bugging. This.*
b8f0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 * opcode causes
b900: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
b910: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 method to swap
b920: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 the file handle
b930: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 with the one.**
b940: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 pointed to by th
b950: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e e pArg argument.
b960: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 This capabilit
b970: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 y is used during
b980: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 testing.** and
b990: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 only needs to be
b9a0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 supported when
b9b0: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 SQLITE_TEST is d
b9c0: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c efined..**.** <l
b9d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
b9e0: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 _WAL_BLOCK]].**
b9f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
ba00: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 L_WAL_BLOCK] is
ba10: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 a signal to the
ba20: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69 VFS layer that i
ba30: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 t might.** be ad
ba40: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c vantageous to bl
ba50: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 ock on the next
ba60: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 WAL lock if the
ba70: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 lock is not imme
ba80: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c diately.** avail
ba90: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73 able. The WAL s
baa0: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20 ubsystem issues
bab0: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69 this signal duri
bac0: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 ng rare.** circu
bad0: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 mstances in orde
bae0: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c r to fix a probl
baf0: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79 em with priority
bb00: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 inversion..** A
bb10: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
bb20: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 ld <em>not</em>
bb30: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f use this file-co
bb40: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ntrol..**.** <li
bb50: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
bb60: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 ZIPVFS]].** The
bb70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 [SQLITE_FCNTL_ZI
bb80: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 PVFS] opcode is
bb90: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a implemented by z
bba0: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 ipvfs only. All
bbb0: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f other.** VFS sho
bbc0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 uld return SQLIT
bbd0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 E_NOTFOUND for t
bbe0: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a his opcode..**.*
bbf0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
bc00: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 CNTL_RBU]].** Th
bc10: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
bc20: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 RBU] opcode is i
bc30: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68 mplemented by th
bc40: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73 e special VFS us
bc50: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 ed by.** the RBU
bc60: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e extension only.
bc70: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 All other VFS
bc80: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 should return SQ
bc90: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f LITE_NOTFOUND fo
bca0: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 r.** this opcode
bcb0: 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a . .** </ul>.*/.
bcc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
bcd0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 CNTL_LOCKSTATE
bce0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 1.#
bcf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
bd00: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 NTL_GET_LOCKPROX
bd10: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 YFILE 2.#d
bd20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
bd30: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TL_SET_LOCKPROXY
bd40: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 FILE 3.#de
bd50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
bd60: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 L_LAST_ERRNO
bd70: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
bd80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
bd90: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 _SIZE_HINT
bda0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 5.#defi
bdb0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
bdc0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 CHUNK_SIZE
bdd0: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 6.#defin
bde0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 e SQLITE_FCNTL_F
bdf0: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 ILE_POINTER
be00: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 7.#define
be10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 SQLITE_FCNTL_SY
be20: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 NC_OMITTED
be30: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 8.#define
be40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
be50: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 32_AV_RETRY
be60: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 9.#define S
be70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 QLITE_FCNTL_PERS
be80: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 IST_WAL
be90: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 10.#define SQ
bea0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 LITE_FCNTL_OVERW
beb0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 RITE
bec0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 11.#define SQL
bed0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d ITE_FCNTL_VFSNAM
bee0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
bef0: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 12.#define SQLI
bf00: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 TE_FCNTL_POWERSA
bf10: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 FE_OVERWRITE
bf20: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 13.#define SQLIT
bf30: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 E_FCNTL_PRAGMA
bf40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
bf50: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
bf60: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c _FCNTL_BUSYHANDL
bf70: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 ER 15
bf80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
bf90: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 FCNTL_TEMPFILENA
bfa0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a ME 16.
bfb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
bfc0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 CNTL_MMAP_SIZE
bfd0: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 18.#
bfe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
bff0: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 NTL_TRACE
c000: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 19.#d
c010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
c020: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 TL_HAS_MOVED
c030: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 20.#de
c040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
c050: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 L_SYNC
c060: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 21.#def
c070: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
c080: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f _COMMIT_PHASETWO
c090: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 22.#defi
c0a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
c0b0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 WIN32_SET_HANDLE
c0c0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 23.#defin
c0d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 e SQLITE_FCNTL_W
c0e0: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 AL_BLOCK
c0f0: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 24.#define
c100: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 SQLITE_FCNTL_ZI
c110: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 PVFS
c120: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 25.#define
c130: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 SQLITE_FCNTL_RBU
c140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
c150: 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 26.#define S
c160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f QLITE_FCNTL_VFS_
c170: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 POINTER
c180: 20 20 20 32 37 0a 0a 2f 2a 20 64 65 70 72 65 63 27../* deprec
c190: 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 ated names */.#d
c1a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 efine SQLITE_GET
c1b0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
c1c0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c SQLITE_FCNTL
c1d0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 _GET_LOCKPROXYFI
c1e0: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 LE.#define SQLIT
c1f0: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 E_SET_LOCKPROXYF
c200: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f ILE SQLITE_
c210: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 FCNTL_SET_LOCKPR
c220: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 OXYFILE.#define
c230: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e SQLITE_LAST_ERRN
c240: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51 O SQ
c250: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f LITE_FCNTL_LAST_
c260: 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 ERRNO.../*.** CA
c270: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 PI3REF: Mutex Ha
c280: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d ndle.**.** The m
c290: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 utex module with
c2a0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 in SQLite define
c2b0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 s [sqlite3_mutex
c2c0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 ] to be an.** ab
c2d0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 stract type for
c2e0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 a mutex object.
c2f0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
c300: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 never looks.**
c310: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 at the internal
c320: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f representation o
c330: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 f an [sqlite3_mu
c340: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a tex]. It only.*
c350: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 * deals with poi
c360: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 nters to the [sq
c370: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a lite3_mutex] obj
c380: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 ect..**.** Mutex
c390: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 es are created u
c3a0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 sing [sqlite3_mu
c3b0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f tex_alloc()]..*/
c3c0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
c3d0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 sqlite3_mutex sq
c3e0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a lite3_mutex;../*
c3f0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
c400: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 Interface Objec
c410: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 t.**.** An insta
c420: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 nce of the sqlit
c430: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 e3_vfs object de
c440: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 fines the interf
c450: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 ace between.** t
c460: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 he SQLite core a
c470: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e nd the underlyin
c480: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 g operating syst
c490: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a em. The "vfs".*
c4a0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 * in the name of
c4b0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e the object stan
c4c0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 ds for "virtual
c4d0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 file system". S
c4e0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c ee.** the [VFS |
c4f0: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 VFS documentati
c500: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 on] for further
c510: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
c520: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 ** The value of
c530: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 the iVersion fie
c540: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 ld is initially
c550: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 1 but may be lar
c560: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 ger in.** future
c570: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
c580: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c ite. Additional
c590: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
c5a0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a ppended to this.
c5b0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 ** object when t
c5c0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 he iVersion valu
c5d0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 e is increased.
c5e0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 Note that the s
c5f0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 tructure.** of t
c600: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f he sqlite3_vfs o
c610: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e bject changes in
c620: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
c630: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 between.** SQLi
c640: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 te version 3.5.9
c650: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 and 3.6.0 and y
c660: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 et the iVersion
c670: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a field was not.**
c680: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a modified..**.**
c690: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 The szOsFile fi
c6a0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 eld is the size
c6b0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 of the subclasse
c6c0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d d [sqlite3_file]
c6d0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 .** structure us
c6e0: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 ed by this VFS.
c6f0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 mxPathname is t
c700: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
c710: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 h of.** a pathna
c720: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a me in this VFS..
c730: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 **.** Registered
c740: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a sqlite3_vfs obj
c750: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e ects are kept on
c760: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 a linked list f
c770: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 ormed by.** the
c780: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 pNext pointer.
c790: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 The [sqlite3_vfs
c7a0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 _register()].**
c7b0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 and [sqlite3_vfs
c7c0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 _unregister()] i
c7d0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 nterfaces manage
c7e0: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e this list.** in
c7f0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 a thread-safe w
c800: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 ay. The [sqlite
c810: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 3_vfs_find()] in
c820: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 terface.** searc
c830: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e hes the list. N
c840: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 either the appli
c850: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 cation code nor
c860: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 the VFS.** imple
c870: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 mentation should
c880: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 use the pNext p
c890: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 ointer..**.** Th
c8a0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 e pNext field is
c8b0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 the only field
c8c0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 in the sqlite3_v
c8d0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 fs.** structure
c8e0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
c8f0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 ever modify. S
c900: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 QLite will only
c910: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 access.** or mod
c920: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 ify this field w
c930: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 hile holding a p
c940: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 articular static
c950: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 mutex..** The a
c960: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
c970: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 d never modify a
c980: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 nything within t
c990: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a he sqlite3_vfs.*
c9a0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 * object once th
c9b0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 e object has bee
c9c0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a n registered..**
c9d0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 .** The zName fi
c9e0: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 eld holds the na
c9f0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f me of the VFS mo
ca00: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 dule. The name
ca10: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 must.** be uniqu
ca20: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 e across all VFS
ca30: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 modules..**.**
ca40: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [[sqlite3_vfs.xO
ca50: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 pen]].** ^SQLite
ca60: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
ca70: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 the zFilename p
ca80: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 arameter to xOpe
ca90: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 n.** is either a
caa0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 NULL pointer or
cab0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
cac0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 .** from xFullPa
cad0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e thname() with an
cae0: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 optional suffix
caf0: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 added..** ^If a
cb00: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 suffix is added
cb10: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d to the zFilenam
cb20: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 e parameter, it
cb30: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 will.** consist
cb40: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 of a single "-"
cb50: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 character follow
cb60: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 ed by no more th
cb70: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 an.** 11 alphanu
cb80: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 meric and/or "-"
cb90: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 characters..**
cba0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 ^SQLite further
cbb0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a guarantees that.
cbc0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 ** the string wi
cbd0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 ll be valid and
cbe0: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 unchanged until
cbf0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 xClose() is.** c
cc00: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f alled. Because o
cc10: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 f the previous s
cc20: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 entence,.** the
cc30: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 [sqlite3_file] c
cc40: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 an safely store
cc50: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
cc60: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 .** filename if
cc70: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 it needs to reme
cc80: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d mber the filenam
cc90: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f e for some reaso
cca0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 n..** If the zFi
ccb0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
ccc0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e to xOpen is a N
ccd0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
cce0: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 xOpen.** must i
ccf0: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 nvent its own te
cd00: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 mporary name for
cd10: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 the file. ^Whe
cd20: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 never the .** xF
cd30: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
cd40: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c r is NULL it wil
cd50: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 l also be the ca
cd60: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 se that the.** f
cd70: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 lags parameter w
cd80: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c ill include [SQL
cd90: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
cda0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 NCLOSE]..**.** T
cdb0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
cdc0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 t to xOpen() inc
cdd0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 ludes all bits s
cde0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 et in.** the fla
cdf0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b gs argument to [
ce00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
ce10: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 )]. Or if [sqli
ce20: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f te3_open()].** o
ce30: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 r [sqlite3_open1
ce40: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 6()] is used, th
ce50: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 en flags include
ce60: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 s at least.** [S
ce70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
ce80: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f RITE] | [SQLITE_
ce90: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a OPEN_CREATE]. .*
cea0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 * If xOpen() ope
ceb0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f ns a file read-o
cec0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 nly then it sets
ced0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a *pOutFlags to.*
cee0: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 * include [SQLIT
cef0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
cf00: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e . Other bits in
cf10: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 *pOutFlags may
cf20: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 be set..**.** ^(
cf30: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f SQLite will also
cf40: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 add one of the
cf50: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 following flags
cf60: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a to the xOpen().*
cf70: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e * call, dependin
cf80: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 g on the object
cf90: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a being opened:.**
cfa0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
cfb0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
cfc0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 AIN_DB].** <li>
cfd0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
cfe0: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c IN_JOURNAL].** <
cff0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
d000: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c N_TEMP_DB].** <l
d010: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
d020: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a _TEMP_JOURNAL].*
d030: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
d040: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
d050: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c B].** <li> [SQL
d060: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 ITE_OPEN_SUBJOUR
d070: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
d080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 QLITE_OPEN_MASTE
d090: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c R_JOURNAL].** <l
d0a0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
d0b0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e _WAL].** </ul>)^
d0c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 .**.** The file
d0d0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 I/O implementati
d0e0: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f on can use the o
d0f0: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 bject type flags
d100: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 to.** change th
d110: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 e way it deals w
d120: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 ith files. For
d130: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c example, an appl
d140: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 ication.** that
d150: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 does not care ab
d160: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 out crash recove
d170: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d ry or rollback m
d180: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 ight make.** the
d190: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e open of a journ
d1a0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e al file a no-op.
d1b0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 Writes to this
d1c0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a journal would.*
d1d0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 * also be no-ops
d1e0: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 , and any attemp
d1f0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f t to read the jo
d200: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 urnal would retu
d210: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 rn.** SQLITE_IOE
d220: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c RR. Or the impl
d230: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 ementation might
d240: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 recognize that
d250: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 a database.** fi
d260: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 le will be doing
d270: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 page-aligned se
d280: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 ctor reads and w
d290: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f rites in a rando
d2a0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 m.** order and s
d2b0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 et up its I/O su
d2c0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e bsystem accordin
d2d0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 gly..**.** SQLit
d2e0: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 e might also add
d2f0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
d300: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 owing flags to t
d310: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a he xOpen method:
d320: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
d330: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e li> [SQLITE_OPEN
d340: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a _DELETEONCLOSE].
d350: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
d360: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a OPEN_EXCLUSIVE].
d370: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 ** </ul>.**.** T
d380: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
d390: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 DELETEONCLOSE] f
d3a0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 lag means the fi
d3b0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 le should be.**
d3c0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 deleted when it
d3d0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 is closed. ^The
d3e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
d3f0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 LETEONCLOSE].**
d400: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 will be set for
d410: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 TEMP databases a
d420: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c nd their journal
d430: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 s, transient.**
d440: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 databases, and s
d450: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a ubjournals..**.*
d460: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f * ^The [SQLITE_O
d470: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 PEN_EXCLUSIVE] f
d480: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 lag is always us
d490: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f ed in conjunctio
d4a0: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 n.** with the [S
d4b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
d4c0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 E] flag, which a
d4d0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 re both directly
d4e0: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f .** analogous to
d4f0: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 the O_EXCL and
d500: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 O_CREAT flags of
d510: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 the POSIX open(
d520: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 ).** API. The S
d530: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
d540: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 SIVE flag, when
d550: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 paired with the
d560: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f .** SQLITE_OPEN_
d570: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 CREATE, is used
d580: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 to indicate that
d590: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 file should alw
d5a0: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 ays.** be create
d5b0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 d, and that it i
d5c0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 s an error if it
d5d0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e already exists.
d5e0: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 .** It is <i>not
d5f0: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 </i> used to ind
d600: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 icate the file s
d610: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 hould be opened
d620: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 .** for exclusiv
d630: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 e access..**.**
d640: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 ^At least szOsFi
d650: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f le bytes of memo
d660: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 ry are allocated
d670: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f by SQLite.** to
d680: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 hold the [sqli
d690: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 te3_file] struct
d6a0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 ure passed as th
d6b0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d e third.** argum
d6c0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 ent to xOpen. T
d6d0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 he xOpen method
d6e0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f does not have to
d6f0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 .** allocate the
d700: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 structure; it s
d710: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 hould just fill
d720: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 it in. Note tha
d730: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d t.** the xOpen m
d740: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 ethod must set t
d750: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e he sqlite3_file.
d760: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 pMethods to eith
d770: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 er.** a valid [s
d780: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
d790: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 s] object or to
d7a0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 NULL. xOpen mus
d7b0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 t do.** this eve
d7c0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 n if the open fa
d7d0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 ils. SQLite exp
d7e0: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 ects that the sq
d7f0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
d800: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 ods.** element w
d810: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 ill be valid aft
d820: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 er xOpen returns
d830: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 regardless of t
d840: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 he success.** or
d850: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 failure of the
d860: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a xOpen call..**.*
d870: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e * [[sqlite3_vfs.
d880: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 xAccess]].** ^Th
d890: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
d8a0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 to xAccess() ma
d8b0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 y be [SQLITE_ACC
d8c0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 ESS_EXISTS].** t
d8d0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 o test for the e
d8e0: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 xistence of a fi
d8f0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 le, or [SQLITE_A
d900: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d CCESS_READWRITE]
d910: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 to.** test whet
d920: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 her a file is re
d930: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 adable and writa
d940: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f ble, or [SQLITE_
d950: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 ACCESS_READ].**
d960: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 to test whether
d970: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 a file is at lea
d980: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 st readable. T
d990: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 he file can be a
d9a0: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a .** directory..*
d9b0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c *.** ^SQLite wil
d9c0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 l always allocat
d9d0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 e at least mxPat
d9e0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f hname+1 bytes fo
d9f0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 r the.** output
da00: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 buffer xFullPath
da10: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 name. The exact
da20: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 size of the out
da30: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 put buffer.** is
da40: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 also passed as
da50: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 a parameter to b
da60: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 oth methods. If
da70: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 the output buff
da80: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 er.** is not lar
da90: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 ge enough, [SQLI
daa0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f TE_CANTOPEN] sho
dab0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e uld be returned.
dac0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a Since this is.*
dad0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 * handled as a f
dae0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 atal error by SQ
daf0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d Lite, vfs implem
db00: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 entations should
db10: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 endeavor.** to
db20: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 prevent this by
db30: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 setting mxPathna
db40: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 me to a sufficie
db50: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 ntly large value
db60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e ..**.** The xRan
db70: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 domness(), xSlee
db80: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d p(), xCurrentTim
db90: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e e(), and xCurren
dba0: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 tTimeInt64().**
dbb0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e interfaces are n
dbc0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 ot strictly a pa
dbd0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 rt of the filesy
dbe0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 stem, but they a
dbf0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 re.** included i
dc00: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 n the VFS struct
dc10: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 ure for complete
dc20: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 ness..** The xRa
dc30: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 ndomness() funct
dc40: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ion attempts to
dc50: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 return nBytes by
dc60: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 tes.** of good-q
dc70: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 uality randomnes
dc80: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 s into zOut. Th
dc90: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 e return value i
dca0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 s.** the actual
dcb0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
dcc0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 of randomness ob
dcd0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 tained..** The x
dce0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 Sleep() method c
dcf0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e auses the callin
dd00: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 g thread to slee
dd10: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 p for at.** leas
dd20: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
dd30: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 microseconds giv
dd40: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 en. ^The xCurre
dd50: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 ntTime().** meth
dd60: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c od returns a Jul
dd70: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 ian Day Number f
dd80: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 or the current d
dd90: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a ate and time as.
dda0: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f ** a floating po
ddb0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 int value..** ^T
ddc0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 he xCurrentTimeI
ddd0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 nt64() method re
dde0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 turns, as an int
ddf0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e eger, the Julian
de00: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d .** Day Number m
de10: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 ultiplied by 864
de20: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 00000 (the numbe
de30: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
de40: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f s in .** a 24-ho
de50: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 ur day). .** ^S
de60: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 QLite will use t
de70: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 he xCurrentTimeI
de80: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f nt64() method to
de90: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 get the current
dea0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d .** date and tim
deb0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 e if that method
dec0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 is available (i
ded0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 f iVersion is 2
dee0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 or .** greater a
def0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 nd the function
df00: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e pointer is not N
df10: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 ULL) and will fa
df20: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 ll back.** to xC
df30: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 urrentTime() if
df40: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 xCurrentTimeInt6
df50: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 4() is unavailab
df60: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 le..**.** ^The x
df70: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c SetSystemCall(),
df80: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 xGetSystemCall(
df90: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 ), and xNestSyst
dfa0: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 emCall() interfa
dfb0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 ces.** are not u
dfc0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 sed by the SQLit
dfd0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f e core. These o
dfe0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 ptional interfac
dff0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a es are provided.
e000: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 ** by some VFSes
e010: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 to facilitate t
e020: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 esting of the VF
e030: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 S code. By overr
e040: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d iding .** system
e050: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 calls with func
e060: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 tions under its
e070: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 control, a test
e080: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 program can.** s
e090: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 imulate faults a
e0a0: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 nd error conditi
e0b0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f ons that would o
e0c0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 therwise be diff
e0d0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f icult.** or impo
e0e0: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 ssible to induce
e0f0: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 . The set of sy
e100: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 stem calls that
e110: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 can be overridde
e120: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d n.** varies from
e130: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 one VFS to anot
e140: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e her, and from on
e150: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 e version of the
e160: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 same VFS to the
e170: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 .** next. Appli
e180: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 cations that use
e190: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
e1a0: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 s must be prepar
e1b0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 ed for any.** or
e1c0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e all of these in
e1d0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e terfaces to be N
e1e0: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 ULL or for their
e1f0: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 behavior to cha
e200: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 nge.** from one
e210: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e release to the n
e220: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ext. Applicatio
e230: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 ns must not atte
e240: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a mpt to access.**
e250: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 any of these me
e260: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 thods if the iVe
e270: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 rsion of the VFS
e280: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e is less than 3.
e290: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
e2a0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 ct sqlite3_vfs s
e2b0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 qlite3_vfs;.type
e2c0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 def void (*sqlit
e2d0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 e3_syscall_ptr)(
e2e0: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 void);.struct sq
e2f0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e lite3_vfs {. in
e300: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 t iVersion;
e310: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 /* Struct
e320: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 ure version numb
e330: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 er (currently 3)
e340: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 */. int szOsFi
e350: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f le; /
e360: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 * Size of subcla
e370: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c ssed sqlite3_fil
e380: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 e */. int mxPat
e390: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 hname;
e3a0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 /* Maximum file
e3b0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 pathname length
e3c0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 */. sqlite3_vfs
e3d0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a *pNext; /*
e3e0: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 Next registered
e3f0: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 VFS */. const
e400: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 char *zName;
e410: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 /* Name of th
e420: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 is virtual file
e430: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 system */. void
e440: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
e450: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 /* Pointer
e460: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 to application-s
e470: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a pecific data */.
e480: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 int (*xOpen)(s
e490: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
e4a0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
e4b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 sqlite3_file*,.
e4c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e in
e4d0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f t flags, int *pO
e4e0: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 utFlags);. int
e4f0: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 (*xDelete)(sqlit
e500: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
e510: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
e520: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 syncDir);. int
e530: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 (*xAccess)(sqlit
e540: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
e550: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
e560: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 flags, int *pRes
e570: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 Out);. int (*xF
e580: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c ullPathname)(sql
e590: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
e5a0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
e5b0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f t nOut, char *zO
e5c0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ut);. void *(*x
e5d0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f DlOpen)(sqlite3_
e5e0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
e5f0: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 *zFilename);.
e600: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 void (*xDlError)
e610: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
e620: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a nt nByte, char *
e630: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 zErrMsg);. void
e640: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c (*(*xDlSym)(sql
e650: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c ite3_vfs*,void*,
e660: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 const char *zSy
e670: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 mbol))(void);.
e680: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 void (*xDlClose)
e690: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 (sqlite3_vfs*, v
e6a0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 oid*);. int (*x
e6b0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 Randomness)(sqli
e6c0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 te3_vfs*, int nB
e6d0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 yte, char *zOut)
e6e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 ;. int (*xSleep
e6f0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e700: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 int microseconds
e710: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 );. int (*xCurr
e720: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 entTime)(sqlite3
e730: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b _vfs*, double*);
e740: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 . int (*xGetLas
e750: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f tError)(sqlite3_
e760: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 vfs*, int, char
e770: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 *);. /*. ** Th
e780: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 e methods above
e790: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 are in version 1
e7a0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 of the sqlite_v
e7b0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 fs object. ** d
e7c0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 efinition. Thos
e7d0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 e that follow ar
e7e0: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 e added in versi
e7f0: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 on 2 or later.
e800: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 */. int (*xCurr
e810: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 entTimeInt64)(sq
e820: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 lite3_vfs*, sqli
e830: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f te3_int64*);. /
e840: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
e850: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
e860: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 versions 1 and 2
e870: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 of the sqlite_v
e880: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 fs object.. **
e890: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 Those below are
e8a0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e for version 3 an
e8b0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a d greater.. */.
e8c0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 int (*xSetSyst
e8d0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f emCall)(sqlite3_
e8e0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
e8f0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 *zName, sqlite3
e900: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 _syscall_ptr);.
e910: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c sqlite3_syscall
e920: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 _ptr (*xGetSyste
e930: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 mCall)(sqlite3_v
e940: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
e950: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 *zName);. const
e960: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 char *(*xNextSy
e970: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 stemCall)(sqlite
e980: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
e990: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a ar *zName);. /*
e9a0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 . ** The method
e9b0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 s above are in v
e9c0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 ersions 1 throug
e9d0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 h 3 of the sqlit
e9e0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 e_vfs object..
e9f0: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 ** New fields ma
ea00: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e y be appended in
ea10: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 figure versions
ea20: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a . The iVersion.
ea30: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 ** value will
ea40: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 increment whenev
ea50: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e er this happens.
ea60: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a . */.};../*.**
ea70: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
ea80: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 for the xAccess
ea90: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a VFS method.**.*
eaa0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
eab0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 constants can be
eac0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 used as the thi
ead0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a rd parameter to.
eae0: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d ** the xAccess m
eaf0: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c ethod of an [sql
eb00: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
eb10: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e . They determin
eb20: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f e.** what kind o
eb30: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 f permissions th
eb40: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
eb50: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e is looking for.
eb60: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
eb70: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 ACCESS_EXISTS, t
eb80: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
eb90: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 d.** simply chec
eba0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
ebb0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 ile exists..** W
ebc0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
ebd0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 S_READWRITE, the
ebe0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
ebf0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
ec00: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 r the named dire
ec10: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 ctory is both re
ec20: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 adable and writa
ec30: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 ble.** (in other
ec40: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 words, if files
ec50: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 can be added, r
ec60: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 emoved, and rena
ec70: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 med within.** th
ec80: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a e directory)..**
ec90: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 The SQLITE_ACCE
eca0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e SS_READWRITE con
ecb0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 stant is current
ecc0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 ly used only by
ecd0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f the.** [temp_sto
ece0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 re_directory pra
ecf0: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 gma], though thi
ed00: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 s could change i
ed10: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 n a future.** re
ed20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e lease of SQLite.
ed30: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
ed40: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 ACCESS_READ, the
ed50: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
ed60: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
ed70: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 r the file is re
ed80: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c adable. The SQL
ed90: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 ITE_ACCESS_READ
eda0: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 constant is.** c
edb0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c urrently unused,
edc0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 though it might
edd0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 be used in a fu
ede0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a ture release of.
edf0: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 ** SQLite..*/.#d
ee00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 efine SQLITE_ACC
ee10: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a ESS_EXISTS 0.
ee20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
ee30: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 CCESS_READWRITE
ee40: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 1 /* Used by P
ee50: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 RAGMA temp_store
ee60: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 _directory */.#d
ee70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 efine SQLITE_ACC
ee80: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 ESS_READ 2
ee90: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a /* Unused */..
eea0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
eeb0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 Flags for the xS
eec0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f hmLock VFS metho
eed0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e d.**.** These in
eee0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
eef0: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f define the vario
ef00: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 us locking opera
ef10: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 tions.** allowed
ef20: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b by the xShmLock
ef30: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 method of [sqli
ef40: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e te3_io_methods].
ef50: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 The.** followi
ef60: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 ng are the only
ef70: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f legal combinatio
ef80: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 ns of flags to t
ef90: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d he.** xShmLock m
efa0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c ethod:.**.** <ul
efb0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 >.** <li> SQLIT
efc0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c E_SHM_LOCK | SQL
efd0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a ITE_SHM_SHARED.*
efe0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
eff0: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 HM_LOCK | SQLITE
f000: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a _SHM_EXCLUSIVE.*
f010: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
f020: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 HM_UNLOCK | SQLI
f030: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a TE_SHM_SHARED.**
f040: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
f050: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 M_UNLOCK | SQLIT
f060: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a E_SHM_EXCLUSIVE.
f070: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 ** </ul>.**.** W
f080: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 hen unlocking, t
f090: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f he same SHARED o
f0a0: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 r EXCLUSIVE flag
f0b0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 must be supplie
f0c0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 d as.** was give
f0d0: 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 n on the corresp
f0e0: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a onding lock. .*
f0f0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 *.** The xShmLoc
f100: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 k method can tra
f110: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 nsition between
f120: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 unlocked and SHA
f130: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 RED or.** betwee
f140: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 n unlocked and E
f150: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 XCLUSIVE. It ca
f160: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 nnot transition
f170: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a between SHARED.*
f180: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e * and EXCLUSIVE.
f190: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
f1a0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 TE_SHM_UNLOCK
f1b0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
f1c0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 LITE_SHM_LOCK
f1d0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
f1e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 SQLITE_SHM_SHARE
f1f0: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e D 4.#defin
f200: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 e SQLITE_SHM_EXC
f210: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a LUSIVE 8../*.
f220: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 ** CAPI3REF: Max
f230: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e imum xShmLock in
f240: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 dex.**.** The xS
f250: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e hmLock method on
f260: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
f270: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 hods] may use va
f280: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 lues.** between
f290: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 0 and this upper
f2a0: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f bound as its "o
f2b0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e ffset" argument.
f2c0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
f2d0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 ore will never a
f2e0: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 ttempt to acquir
f2f0: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a e or release a.*
f300: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f * lock outside o
f310: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a f this range.*/.
f320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
f330: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 HM_NLOCK
f340: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 8.../*.** CAPI3R
f350: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 EF: Initialize T
f360: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
f370: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c y.**.** ^The sql
f380: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
f390: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 ) routine initia
f3a0: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c lizes the.** SQL
f3b0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 ite library. ^T
f3c0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 he sqlite3_shutd
f3d0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a own() routine.**
f3e0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 deallocates any
f3f0: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 resources that
f400: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 were allocated b
f410: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 y sqlite3_initia
f420: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 lize()..** These
f430: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 routines are de
f440: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e signed to aid in
f450: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c process initial
f460: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 ization and.** s
f470: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 hutdown on embed
f480: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f ded systems. Wo
f490: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 rkstation applic
f4a0: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 ations using.**
f4b0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 SQLite normally
f4c0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 do not need to i
f4d0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 nvoke either of
f4e0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
f4f0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 **.** A call to
f500: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
f510: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 ze() is an "effe
f520: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 ctive" call if i
f530: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 t is.** the firs
f540: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 t time sqlite3_i
f550: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
f560: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 nvoked during th
f570: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a e lifetime of.**
f580: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 the process, or
f590: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 if it is the fi
f5a0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 rst time sqlite3
f5b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
f5c0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c invoked.** foll
f5d0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 owing a call to
f5e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
f5f0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 (). ^(Only an e
f600: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a ffective call.**
f610: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 of sqlite3_init
f620: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e ialize() does an
f630: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e y initialization
f640: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c . All other cal
f650: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 ls.** are harmle
f660: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a ss no-ops.)^.**.
f670: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c ** A call to sql
f680: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
f690: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 is an "effective
f6a0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 " call if it is
f6b0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c the first.** cal
f6c0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
f6d0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 tdown() since th
f6e0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 e last sqlite3_i
f6f0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 nitialize(). ^(
f700: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 Only.** an effec
f710: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c tive call to sql
f720: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
f730: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 does any deiniti
f740: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c alization..** Al
f750: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 l other valid ca
f760: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 lls to sqlite3_s
f770: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 hutdown() are ha
f780: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e rmless no-ops.)^
f790: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
f7a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
f7b0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 interface is thr
f7c0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c eadsafe, but sql
f7d0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a ite3_shutdown().
f7e0: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 ** is not. The
f7f0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
f800: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 () interface mus
f810: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 t only be called
f820: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c from a.** singl
f830: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f e thread. All o
f840: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f pen [database co
f850: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 nnections] must
f860: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c be closed and al
f870: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 l.** other SQLit
f880: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 e resources must
f890: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
f8a0: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e prior to invokin
f8b0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 g.** sqlite3_shu
f8c0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 tdown()..**.** A
f8d0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 mong other thing
f8e0: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 s, ^sqlite3_init
f8f0: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e ialize() will in
f900: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
f910: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 os_init(). Simi
f920: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f larly, ^sqlite3_
f930: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 shutdown().** wi
f940: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ll invoke sqlite
f950: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 3_os_end()..**.*
f960: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
f970: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
f980: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ine returns [SQL
f990: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
f9a0: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 ss..** ^If for s
f9b0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 ome reason, sqli
f9c0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
f9d0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e is unable to in
f9e0: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 itialize.** the
f9f0: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 library (perhaps
fa00: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f it is unable to
fa10: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 allocate a need
fa20: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 ed resource such
fa30: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 .** as a mutex)
fa40: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 it returns an [e
fa50: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 rror code] other
fa60: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b than [SQLITE_OK
fa70: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ]..**.** ^The sq
fa80: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
fa90: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 () routine is ca
faa0: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 lled internally
fab0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a by many other.**
fac0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
fad0: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 es so that an ap
fae0: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c plication usuall
faf0: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 y does not need
fb00: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c to.** invoke sql
fb10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
fb20: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 ) directly. For
fb30: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 example, [sqlit
fb40: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 e3_open()].** ca
fb50: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 lls sqlite3_init
fb60: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 ialize() so the
fb70: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 SQLite library w
fb80: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 ill be automatic
fb90: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 ally.** initiali
fba0: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 zed when [sqlite
fbb0: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 3_open()] is cal
fbc0: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f led if it has no
fbd0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 t be initialized
fbe0: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 .** already. ^H
fbf0: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 owever, if SQLit
fc00: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
fc10: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
fc20: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a MIT_AUTOINIT].**
fc30: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
fc40: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 tion, then the a
fc50: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 utomatic calls t
fc60: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 o sqlite3_initia
fc70: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d lize().** are om
fc80: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 itted and the ap
fc90: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 plication must c
fca0: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 all sqlite3_init
fcb0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c ialize() directl
fcc0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 y.** prior to us
fcd0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 ing any other SQ
fce0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
fcf0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 For maximum por
fd00: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 tability,.** it
fd10: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 is recommended t
fd20: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 hat applications
fd30: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 always invoke s
fd40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
fd50: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 e().** directly
fd60: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 prior to using a
fd70: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ny other SQLite
fd80: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 interface. Futu
fd90: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f re releases.** o
fda0: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 f SQLite may req
fdb0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f uire this. In o
fdc0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
fdd0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 behavior exhibit
fde0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 ed.** when SQLit
fdf0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
fe00: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f th [SQLITE_OMIT_
fe10: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 AUTOINIT] might
fe20: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 become the.** de
fe30: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 fault behavior i
fe40: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 n some future re
fe50: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e lease of SQLite.
fe60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
fe70: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 e3_os_init() rou
fe80: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 tine does operat
fe90: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
fea0: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a fic.** initializ
feb0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c ation of the SQL
fec0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 ite library. Th
fed0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 e sqlite3_os_end
fee0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e ().** routine un
fef0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 does the effect
ff00: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e of sqlite3_os_in
ff10: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 it(). Typical t
ff20: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 asks.** performe
ff30: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 d by these routi
ff40: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f nes include allo
ff50: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f cation or deallo
ff60: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 cation.** of sta
ff70: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 tic resources, i
ff80: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 nitialization of
ff90: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 global variable
ffa0: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 s,.** setting up
ffb0: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 a default [sqli
ffc0: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c te3_vfs] module,
ffd0: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a or setting up.*
ffe0: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 * a default conf
fff0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 iguration using
10000 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
10010 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 )]..**.** The ap
10020 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
10030 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 never invoke ei
10040 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f ther sqlite3_os_
10050 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c init().** or sql
10060 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 ite3_os_end() di
10070 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 rectly. The app
10080 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
10090 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 only invoke.** s
100a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
100b0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
100c0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 shutdown(). The
100d0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
100e0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
100f0 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 is called automa
10100 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 tically by sqlit
10110 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
10120 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f and.** sqlite3_o
10130 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 s_end() is calle
10140 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 d by sqlite3_shu
10150 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 tdown(). Approp
10160 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 riate.** impleme
10170 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c ntations for sql
10180 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 ite3_os_init() a
10190 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nd sqlite3_os_en
101a0 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 d().** are built
101b0 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 into SQLite whe
101c0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 n it is compiled
101d0 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f for Unix, Windo
101e0 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 ws, or OS/2..**
101f0 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 When [custom bui
10200 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 lds | built for
10210 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d other platforms]
10220 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b .** (using the [
10230 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d SQLITE_OS_OTHER=
10240 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 1] compile-time.
10250 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 ** option) the a
10260 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
10270 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c supply a suitabl
10280 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
10290 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
102a0 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 os_init() and sq
102b0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 lite3_os_end().
102c0 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d An application-
102d0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c supplied.** impl
102e0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 ementation of sq
102f0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
10300 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e or sqlite3_os_en
10310 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 d().** must retu
10320 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f rn [SQLITE_OK] o
10330 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f n success and so
10340 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 me other [error
10350 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 code] upon.** fa
10360 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ilure..*/.int sq
10370 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
10380 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 (void);.int sqli
10390 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 te3_shutdown(voi
103a0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f d);.int sqlite3_
103b0 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 os_init(void);.i
103c0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nt sqlite3_os_en
103d0 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 d(void);../*.**
103e0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
103f0 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 uring The SQLite
10400 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 Library.**.** T
10410 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 he sqlite3_confi
10420 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 g() interface is
10430 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c used to make gl
10440 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 obal configurati
10450 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f on.** changes to
10460 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 SQLite in order
10470 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 to tune SQLite
10480 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 to the specific
10490 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 needs of.** the
104a0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 application. Th
104b0 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 e default config
104c0 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d uration is recom
104d0 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a mended for most.
104e0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** applications
104f0 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 and so this rout
10500 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e ine is usually n
10510 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 ot necessary. I
10520 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 t is.** provided
10530 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 to support rare
10540 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 applications wi
10550 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 th unusual needs
10560 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 ..**.** <b>The s
10570 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
10580 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 interface is not
10590 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65 threadsafe. The
105a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
105b0 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 must ensure that
105c0 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 no other SQLite
105d0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
105e0 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 invoked by other
105f0 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c .** threads whil
10600 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
10610 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f () is running.</
10620 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c b>.**.** The sql
10630 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
10640 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f terface.** may o
10650 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 nly be invoked p
10660 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 rior to library
10670 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 initialization u
10680 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
10690 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f _initialize()] o
106a0 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e r after shutdown
106b0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 by [sqlite3_shu
106c0 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 tdown()]..** ^If
106d0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
106e0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 ) is called afte
106f0 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 r [sqlite3_initi
10700 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 alize()] and bef
10710 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ore.** [sqlite3_
10720 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e shutdown()] then
10730 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 it will return
10740 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a SQLITE_MISUSE..*
10750 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c * Note, however,
10760 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 that ^sqlite3_c
10770 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 onfig() can be c
10780 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 alled as part of
10790 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e the.** implemen
107a0 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 tation of an app
107b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
107c0 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 [sqlite3_os_ini
107d0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 t()]..**.** The
107e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
107f0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 o sqlite3_config
10800 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 () is an integer
10810 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 .** [configurati
10820 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 on option] that
10830 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 determines.** wh
10840 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 at property of S
10850 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 QLite is to be c
10860 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 onfigured. Subs
10870 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 equent arguments
10880 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 .** vary dependi
10890 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 ng on the [confi
108a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d guration option]
108b0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 .** in the first
108c0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
108d0 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 ^When a configu
108e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
108f0 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f set, sqlite3_co
10900 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b nfig() returns [
10910 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e SQLITE_OK]..** ^
10920 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 If the option is
10930 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 unknown or SQLi
10940 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 te is unable to
10950 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a set the option.*
10960 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 * then this rout
10970 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f ine returns a no
10980 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f n-zero [error co
10990 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 de]..*/.int sqli
109a0 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 te3_config(int,
109b0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ...);../*.** CAP
109c0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 I3REF: Configure
109d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
109e0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a tions.** METHOD:
109f0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 sqlite3.**.** T
10a00 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f he sqlite3_db_co
10a10 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
10a20 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 is used to make
10a30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a configuration.*
10a40 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b * changes to a [
10a50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
10a60 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 ion]. The inter
10a70 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 face is similar
10a80 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
10a90 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 onfig()] except
10aa0 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 that the changes
10ab0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 apply to a sing
10ac0 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 le.** [database
10ad0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 connection] (spe
10ae0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 cified in the fi
10af0 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a rst argument)..*
10b00 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 *.** The second
10b10 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
10b20 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c te3_db_config(D,
10b30 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a V,...) is the.*
10b40 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 * [SQLITE_DBCONF
10b50 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 IG_LOOKASIDE | c
10b60 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 onfiguration ver
10b70 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 b] - an integer
10b80 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e code .** that in
10b90 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 dicates what asp
10ba0 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 ect of the [data
10bb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
10bc0 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 is being config
10bd0 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 ured..** Subsequ
10be0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 ent arguments va
10bf0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ry depending on
10c00 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f the configuratio
10c10 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 n verb..**.** ^C
10c20 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
10c30 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 db_config() retu
10c40 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 rn SQLITE_OK if
10c50 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 and only if.** t
10c60 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 he call is consi
10c70 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c dered successful
10c80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
10c90 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 _db_config(sqlit
10ca0 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e e3*, int op, ...
10cb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
10cc0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 EF: Memory Alloc
10cd0 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a ation Routines.*
10ce0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
10cf0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
10d00 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 defines the inte
10d10 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 rface between SQ
10d20 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d Lite.** and low-
10d30 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c level memory all
10d40 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
10d50 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a ..**.** This obj
10d60 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f ect is used in o
10d70 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e nly one place in
10d80 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 the SQLite inte
10d90 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e rface..** A poin
10da0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
10db0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
10dc0 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e t is the argumen
10dd0 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 t to.** [sqlite3
10de0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 _config()] when
10df0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f the configuratio
10e00 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b n option is.** [
10e10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
10e20 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 LLOC] or [SQLITE
10e30 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
10e40 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 C]. .** By crea
10e50 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 ting an instance
10e60 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a of this object.
10e70 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 ** and passing i
10e80 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
10e90 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f nfig]([SQLITE_CO
10ea0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a NFIG_MALLOC]).**
10eb0 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 during configur
10ec0 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 ation, an applic
10ed0 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 ation can specif
10ee0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 y an alternative
10ef0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
10f00 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 ation subsystem
10f10 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 for SQLite to us
10f20 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 e for all of its
10f30 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f .** dynamic memo
10f40 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 ry needs..**.**
10f50 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 Note that SQLite
10f60 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 comes with seve
10f70 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 ral [built-in me
10f80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d mory allocators]
10f90 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 .** that are per
10fa0 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 fectly adequate
10fb0 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c for the overwhel
10fc0 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 ming majority of
10fd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
10fe0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f and that this o
10ff0 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 bject is only us
11000 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d eful to a tiny m
11010 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 inority of appli
11020 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 cations.** with
11030 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f specialized memo
11040 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 ry allocation re
11050 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 quirements. Thi
11060 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 s object is.** a
11070 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 lso used during
11080 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 testing of SQLit
11090 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 e in order to sp
110a0 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 ecify an alterna
110b0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 tive.** memory a
110c0 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 llocator that si
110d0 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f mulates memory o
110e0 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e ut-of-memory con
110f0 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 ditions in.** or
11100 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 der to verify th
11110 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 at SQLite recove
11120 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 rs gracefully fr
11130 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 om such.** condi
11140 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tions..**.** The
11150 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c xMalloc, xReall
11160 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 oc, and xFree me
11170 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 thods must work
11180 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c like the.** mall
11190 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 oc(), realloc()
111a0 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 and free() funct
111b0 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 ions from the st
111c0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
111d0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 ..** ^SQLite gua
111e0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 rantees that the
111f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
11200 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 to.** xRealloc
11210 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 is always a valu
11220 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 e returned by a
11230 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 prior call to xR
11240 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 oundup..**.** xS
11250 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 ize should retur
11260 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 n the allocated
11270 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 size of a memory
11280 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 allocation.** p
11290 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e reviously obtain
112a0 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 ed from xMalloc
112b0 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 or xRealloc. Th
112c0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
112d0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 .** is always at
112e0 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 least as big as
112f0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 the requested s
11300 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c ize but may be l
11310 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 arger..**.** The
11320 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 xRoundup method
11330 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f returns what wo
11340 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 uld be the alloc
11350 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 ated size of.**
11360 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
11370 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 ion given a part
11380 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 icular requested
11390 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d size. Most mem
113a0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 ory.** allocator
113b0 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 s round up memor
113c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 y allocations at
113d0 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 least to the ne
113e0 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f xt multiple.** o
113f0 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 f 8. Some alloc
11400 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 ators round up t
11410 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 o a larger multi
11420 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 ple or to a powe
11430 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 r of 2..** Every
11440 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
11450 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e on request comin
11460 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 g in through [sq
11470 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a lite3_malloc()].
11480 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 ** or [sqlite3_r
11490 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 ealloc()] first
114a0 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 calls xRoundup.
114b0 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 If xRoundup ret
114c0 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 urns 0, .** that
114d0 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 causes the corr
114e0 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 esponding memory
114f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 allocation to f
11500 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ail..**.** The x
11510 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 Init method init
11520 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f ializes the memo
11530 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 ry allocator. F
11540 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 or example,.** i
11550 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 t might allocate
11560 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 any require mut
11570 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 exes or initiali
11580 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 ze internal data
11590 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 .** structures.
115a0 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d The xShutdown m
115b0 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 ethod is invoked
115c0 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 (indirectly) by
115d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 .** [sqlite3_shu
115e0 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f tdown()] and sho
115f0 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 uld deallocate a
11600 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 ny resources acq
11610 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 uired.** by xIni
11620 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 t. The pAppData
11630 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 pointer is used
11640 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 as the only par
11650 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e ameter to.** xIn
11660 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e it and xShutdown
11670 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 ..**.** SQLite h
11680 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 olds the [SQLITE
11690 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 _MUTEX_STATIC_MA
116a0 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e STER] mutex when
116b0 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 it invokes.** t
116c0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c he xInit method,
116d0 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 so the xInit me
116e0 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 thod need not be
116f0 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 threadsafe. Th
11700 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d e.** xShutdown m
11710 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 ethod is only ca
11720 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 lled from [sqlit
11730 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 e3_shutdown()] s
11740 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 o it does.** not
11750 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 need to be thre
11760 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 adsafe either.
11770 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 For all other me
11780 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a thods, SQLite.**
11790 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 holds the [SQLI
117a0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
117b0 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f MEM] mutex as lo
117c0 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 ng as the.** [SQ
117d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
117e0 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 TATUS] configura
117f0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 tion option is t
11800 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a urned on (which.
11810 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 ** it is by defa
11820 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 ult) and so the
11830 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f methods are auto
11840 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c matically serial
11850 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 ized..** However
11860 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e , if [SQLITE_CON
11870 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 FIG_MEMSTATUS] i
11880 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e s disabled, then
11890 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 the other.** me
118a0 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 thods must be th
118b0 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 readsafe or else
118c0 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 make their own
118d0 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 arrangements for
118e0 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f .** serializatio
118f0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 n..**.** SQLite
11900 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b will never invok
11910 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 e xInit() more t
11920 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 han once without
11930 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a an intervening.
11940 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 ** call to xShut
11950 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 down()..*/.typed
11960 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
11970 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 3_mem_methods sq
11980 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
11990 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 s;.struct sqlite
119a0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 3_mem_methods {.
119b0 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f void *(*xMallo
119c0 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 c)(int);
119d0 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 /* Memory alloc
119e0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a ation function *
119f0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 /. void (*xFree
11a00 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
11a10 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 /* Free a pri
11a20 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f or allocation */
11a30 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c . void *(*xReal
11a40 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b loc)(void*,int);
11a50 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 /* Resize an a
11a60 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 llocation */. i
11a70 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 nt (*xSize)(void
11a80 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a *); /*
11a90 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 Return the size
11aa0 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f of an allocatio
11ab0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f n */. int (*xRo
11ac0 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 undup)(int);
11ad0 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 /* Round u
11ae0 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 p request size t
11af0 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a o allocation siz
11b00 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e e */. int (*xIn
11b10 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 it)(void*);
11b20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c /* Initial
11b30 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 ize the memory a
11b40 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f llocator */. vo
11b50 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 id (*xShutdown)(
11b60 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 void*); /*
11b70 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 Deinitialize the
11b80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
11b90 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 r */. void *pAp
11ba0 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 pData;
11bb0 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e /* Argumen
11bc0 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 t to xInit() and
11bd0 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a xShutdown() */.
11be0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
11bf0 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f EF: Configuratio
11c00 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 n Options.** KEY
11c10 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 WORDS: {configur
11c20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a ation option}.**
11c30 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
11c40 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 nts are the avai
11c50 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f lable integer co
11c60 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
11c70 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 ons that.** can
11c80 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
11c90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
11ca0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
11cb0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
11cc0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
11cd0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
11ce0 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
11cf0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
11d00 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
11d10 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
11d20 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
11d30 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
11d40 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
11d50 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
11d60 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
11d70 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
11d80 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 ite3_config()] t
11d90 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
11da0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 .** the call wor
11db0 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ked. The [sqlit
11dc0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 e3_config()] int
11dd0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
11de0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
11df0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
11e00 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
11e10 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
11e20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
11e30 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
11e40 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
11e50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
11e60 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 _SINGLETHREAD]]
11e70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
11e80 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f G_SINGLETHREAD</
11e90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
11ea0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
11eb0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
11ec0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 . ^This option
11ed0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 sets the.** [thr
11ee0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 eading mode] to
11ef0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 Single-thread.
11f00 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
11f10 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 it disables.** a
11f20 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 ll mutexing and
11f30 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f puts SQLite into
11f40 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 a mode where it
11f50 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 can only be use
11f60 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 d.** by a single
11f70 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 thread. ^If S
11f80 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
11f90 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 d with.** the [S
11fa0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
11fb0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 | SQLITE_THREAD
11fc0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d SAFE=0] compile-
11fd0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e time option then
11fe0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f .** it is not po
11ff0 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 ssible to change
12000 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
12010 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 mode] from its d
12020 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 efault.** value
12030 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 of Single-thread
12040 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 and so [sqlite3
12050 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 _config()] will
12060 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 return .** [SQLI
12070 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c TE_ERROR] if cal
12080 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c led with the SQL
12090 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
120a0 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 ETHREAD.** confi
120b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e guration option.
120c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
120d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
120e0 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 ITHREAD]] <dt>SQ
120f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
12100 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 ITHREAD</dt>.**
12110 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f <dd>There are no
12120 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
12130 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 is option. ^Thi
12140 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 s option sets th
12150 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 e.** [threading
12160 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 mode] to Multi-t
12170 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 hread. In other
12180 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 words, it disab
12190 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 les.** mutexing
121a0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
121b0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 nection] and [pr
121c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
121d0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 ] objects..** Th
121e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 e application is
121f0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
12200 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 serializing acc
12210 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 ess to.** [datab
12220 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
12230 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
12240 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 tatements]. But
12250 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a other mutexes.*
12260 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f * are enabled so
12270 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
12280 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 l be safe to use
12290 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 in a multi-thre
122a0 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d aded.** environm
122b0 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e ent as long as n
122c0 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 o two threads at
122d0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 tempt to use the
122e0 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 same.** [databa
122f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
12300 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e t the same time.
12310 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 ^If SQLite is
12320 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
12330 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
12340 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
12350 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
12360 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
12370 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 on then.** it is
12380 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f not possible to
12390 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 set the Multi-t
123a0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 hread [threading
123b0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 mode] and.** [s
123c0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
123d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
123e0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
123f0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a alled with the.*
12400 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f * SQLITE_CONFIG_
12410 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 MULTITHREAD conf
12420 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
12430 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
12440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
12450 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 IALIZED]] <dt>SQ
12460 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
12470 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c ALIZED</dt>.** <
12480 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 dd>There are no
12490 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 arguments to thi
124a0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 s option. ^This
124b0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 option sets the
124c0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d .** [threading m
124d0 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a ode] to Serializ
124e0 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 ed. In other wor
124f0 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 ds, this option
12500 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d enables.** all m
12510 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 utexes including
12520 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a the recursive.*
12530 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 * mutexes on [da
12540 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
12550 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 n] and [prepared
12560 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 statement] obje
12570 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 cts..** In this
12580 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 mode (which is t
12590 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 he default when
125a0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
125b0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 ed with.** [SQLI
125c0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d TE_THREADSAFE=1]
125d0 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 ) the SQLite lib
125e0 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 rary will itself
125f0 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 serialize acces
12600 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 s.** to [databas
12610 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 e connections] a
12620 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
12630 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 tements] so that
12640 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 the.** applicat
12650 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 ion is free to u
12660 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 se the same [dat
12670 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
12680 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 ] or the.** same
12690 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
126a0 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 ment] in differe
126b0 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 nt threads at th
126c0 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 e same time..**
126d0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
126e0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
126f0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
12700 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
12710 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
12720 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
12730 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e then.** it is n
12740 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 ot possible to s
12750 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 et the Serialize
12760 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 d [threading mod
12770 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 e] and.** [sqlit
12780 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c e3_config()] wil
12790 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
127a0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 _ERROR] if calle
127b0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 d with the.** SQ
127c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
127d0 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 ALIZED configura
127e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 tion option.</dd
127f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
12800 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d _CONFIG_MALLOC]]
12810 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
12820 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a IG_MALLOC</dt>.*
12830 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
12840 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
12850 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 C option takes a
12860 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
12870 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 which is .** a
12880 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
12890 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
128a0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
128b0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a ds] structure..*
128c0 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 * The argument s
128d0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 pecifies.** alte
128e0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 rnative low-leve
128f0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
12900 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ion routines to
12910 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 be used in place
12920 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 of.** the memor
12930 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
12940 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f tines built into
12950 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 SQLite.)^ ^SQLi
12960 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 te makes.** its
12970 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 own private copy
12980 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 of the content
12990 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
129a0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
129b0 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 ucture.** before
129c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
129d0 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 nfig()] call ret
129e0 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a urns.</dd>.**.**
129f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
12a00 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 _GETMALLOC]] <dt
12a10 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
12a20 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a ETMALLOC</dt>.**
12a30 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 <dd> ^(The SQLI
12a40 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
12a50 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 LOC option takes
12a60 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
12a70 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 nt which.** is a
12a80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
12a90 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
12aa0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
12ab0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a ods] structure..
12ac0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
12ad0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 mem_methods].**
12ae0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c structure is fil
12af0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 led with the cur
12b00 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d rently defined m
12b10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
12b20 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 routines.)^.**
12b30 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 This option can
12b40 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c be used to overl
12b50 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 oad the default
12b60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
12b70 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 n.** routines wi
12b80 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 th a wrapper tha
12b90 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 t simulations me
12ba0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12bb0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 failure or.** tr
12bc0 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 acks memory usag
12bd0 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 e, for example.
12be0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
12bf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
12c00 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 TATUS]] <dt>SQLI
12c10 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
12c20 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TUS</dt>.** <dd>
12c30 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^The SQLITE_CON
12c40 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 FIG_MEMSTATUS op
12c50 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c tion takes singl
12c60 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 e argument of ty
12c70 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 pe int,.** inter
12c80 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c preted as a bool
12c90 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c ean, which enabl
12ca0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
12cb0 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 he collection of
12cc0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
12cd0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 ation statistics
12ce0 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 . ^(When memory
12cf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
12d00 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 stics are.** dis
12d10 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f abled, the follo
12d20 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 wing SQLite inte
12d30 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f rfaces become no
12d40 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a n-operational:.*
12d50 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c * <ul>.** <l
12d60 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f i> [sqlite3_memo
12d70 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 ry_used()].**
12d80 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 <li> [sqlite3_me
12d90 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
12da0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
12db0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c ite3_soft_heap_l
12dc0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c imit64()].** <
12dd0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 li> [sqlite3_sta
12de0 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f tus64()].** </
12df0 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 ul>)^.** ^Memory
12e00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
12e10 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c istics are enabl
12e20 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e ed by default un
12e30 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a less SQLite is.*
12e40 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 * compiled with
12e50 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f [SQLITE_DEFAULT_
12e60 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 MEMSTATUS]=0 in
12e70 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 which case memor
12e80 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 y.** allocation
12e90 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 statistics are d
12ea0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
12eb0 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a lt..** </dd>.**.
12ec0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
12ed0 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 IG_SCRATCH]] <dt
12ee0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
12ef0 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c CRATCH</dt>.** <
12f00 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f dd> ^The SQLITE_
12f10 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f CONFIG_SCRATCH o
12f20 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 ption specifies
12f30 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 a static memory
12f40 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 buffer.** that S
12f50 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f QLite can use fo
12f60 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 r scratch memory
12f70 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 . ^(There are t
12f80 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a hree arguments.*
12f90 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 * to SQLITE_CONF
12fa0 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 IG_SCRATCH: A p
12fb0 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 ointer an 8-byte
12fc0 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f .** aligned memo
12fd0 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 ry buffer from w
12fe0 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68 hich the scratch
12ff0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c allocations wil
13000 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 l be.** drawn, t
13010 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 he size of each
13020 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 scratch allocati
13030 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 on (sz),.** and
13040 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 the maximum numb
13050 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c er of scratch al
13060 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e locations (N).)^
13070 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
13080 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 gument must be a
13090 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 pointer to an 8
130a0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 -byte aligned bu
130b0 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 ffer.** of at le
130c0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f ast sz*N bytes o
130d0 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 f memory..** ^SQ
130e0 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 Lite will not us
130f0 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 e more than one
13100 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 scratch buffers
13110 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e per thread..** ^
13120 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 SQLite will neve
13130 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61 r request a scra
13140 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 tch buffer that
13150 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a is more than 6.*
13160 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 * times the data
13170 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a base page size..
13180 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 ** ^If SQLite ne
13190 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 eds needs additi
131a0 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 onal.** scratch
131b0 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 memory beyond wh
131c0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 at is provided b
131d0 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 y this configura
131e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 tion option, the
131f0 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d n .** [sqlite3_m
13200 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 alloc()] will be
13210 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 used to obtain
13220 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 the memory neede
13230 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 d.<p>.** ^When t
13240 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 he application p
13250 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 rovides any amou
13260 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 nt of scratch me
13270 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 mory using.** SQ
13280 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
13290 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 TCH, SQLite avoi
132a0 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c ds unnecessary l
132b0 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 arge.** [sqlite3
132c0 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c _malloc|heap all
132d0 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 ocations]..** Th
132e0 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 is can help [Rob
132f0 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e son proof|preven
13300 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
13310 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 ion failures] du
13320 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 e to heap.** fra
13330 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f gmentation in lo
13340 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 w-memory embedde
13350 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f d systems..** </
13360 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
13370 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
13380 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 CHE]] <dt>SQLITE
13390 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
133a0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e E</dt>.** <dd> ^
133b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
133c0 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 G_PAGECACHE opti
133d0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d on specifies a m
133e0 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 emory pool.** th
133f0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 at SQLite can us
13400 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 e for the databa
13410 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 se page cache wi
13420 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 th the default p
13430 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 age.** cache imp
13440 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a lementation. .*
13450 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 * This configura
13460 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 tion option is a
13470 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 no-op if an app
13480 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 lication-define
13490 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d page.** cache im
134a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
134b0 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 loaded using the
134c0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
134d0 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 PCACHE2]..** ^Th
134e0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
134f0 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 guments to SQLIT
13500 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
13510 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f HE: A pointer to
13520 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e .** 8-byte align
13530 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 ed memory (pMem)
13540 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 , the size of ea
13550 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 ch page cache li
13560 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 ne (sz),.** and
13570 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 the number of ca
13580 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a che lines (N)..*
13590 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e * The sz argumen
135a0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 t should be the
135b0 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 size of the larg
135c0 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 est database pag
135d0 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 e.** (a power of
135e0 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 two between 512
135f0 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 and 65536) plus
13600 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 some extra byte
13610 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 s for each.** pa
13620 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 ge header. ^The
13630 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 number of extra
13640 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 bytes needed by
13650 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 the page header
13660 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 .** can be deter
13670 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c mined using [SQL
13680 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
13690 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 E_HDRSZ]..** ^It
136a0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 is harmless, ap
136b0 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 art from the was
136c0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 ted memory,.** f
136d0 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 or the sz parame
136e0 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 ter to be larger
136f0 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e than necessary.
13700 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 The pMem.** ar
13710 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 gument must be e
13720 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 ither a NULL poi
13730 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 nter or a pointe
13740 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a r to an 8-byte.*
13750 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 * aligned block
13760 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 of memory of at
13770 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 least sz*N bytes
13780 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 , otherwise.** s
13790 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 ubsequent behavi
137a0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e or is undefined.
137b0 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 .** ^When pMem i
137c0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 s not NULL, SQLi
137d0 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 te will strive t
137e0 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 o use the memory
137f0 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 provided.** to
13800 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63 satisfy page cac
13810 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e he needs, fallin
13820 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 g back to [sqlit
13830 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a e3_malloc()] if.
13840 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20 ** a page cache
13850 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 line is larger t
13860 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 han sz bytes or
13870 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d if all of the pM
13880 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 em buffer.** is
13890 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 exhausted..** ^I
138a0 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 f pMem is NULL a
138b0 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f nd N is non-zero
138c0 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 , then each data
138d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
138e0 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 ** does an initi
138f0 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 al bulk allocati
13900 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 on for page cach
13910 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d e memory.** from
13920 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
13930 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 ()] sufficient f
13940 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 or N cache lines
13950 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 if N is positiv
13960 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 e or.** of -1024
13970 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 *N bytes if N is
13980 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 negative, . ^If
13990 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 additional.** p
139a0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 age cache memory
139b0 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e is needed beyon
139c0 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 d what is provid
139d0 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 ed by the initia
139e0 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c l.** allocation,
139f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 then SQLite goe
13a00 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 s to [sqlite3_ma
13a10 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 lloc()] separate
13a20 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 ly for each.** a
13a30 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 dditional cache
13a40 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a line. </dd>.**.*
13a50 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
13a60 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c G_HEAP]] <dt>SQL
13a70 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c ITE_CONFIG_HEAP<
13a80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
13a90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
13aa0 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 HEAP option spec
13ab0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d ifies a static m
13ac0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a emory buffer .**
13ad0 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
13ae0 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 l use for all of
13af0 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d its dynamic mem
13b00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
13b10 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 eeds.** beyond t
13b20 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f hose provided fo
13b30 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e r by [SQLITE_CON
13b40 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 FIG_SCRATCH] and
13b50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
13b60 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a IG_PAGECACHE]..*
13b70 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f * ^The SQLITE_CO
13b80 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e NFIG_HEAP option
13b90 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 is only availab
13ba0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 le if SQLite is
13bb0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 compiled.** with
13bc0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
13bd0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 ENABLE_MEMSYS3]
13be0 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c or [SQLITE_ENABL
13bf0 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 E_MEMSYS5] and r
13c00 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 eturns.** [SQLIT
13c10 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f E_ERROR] if invo
13c20 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a ked otherwise..*
13c30 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 * ^There are thr
13c40 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 ee arguments to
13c50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
13c60 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 AP:.** An 8-byte
13c70 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 aligned pointer
13c80 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a to the memory,.
13c90 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
13ca0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 bytes in the me
13cb0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 mory buffer, and
13cc0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
13cd0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a ocation size..**
13ce0 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 ^If the first p
13cf0 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f ointer (the memo
13d00 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e ry pointer) is N
13d10 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ULL, then SQLite
13d20 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 reverts.** to u
13d30 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 sing its default
13d40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
13d50 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 r (the system ma
13d60 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 lloc() implement
13d70 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 ation),.** undoi
13d80 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 ng any prior inv
13d90 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 ocation of [SQLI
13da0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
13db0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d ]. ^If the.** m
13dc0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 emory pointer is
13dd0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 not NULL then t
13de0 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d he alternative m
13df0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
13e00 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f or is engaged to
13e10 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 handle all of S
13e20 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c QLites memory al
13e30 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a location needs..
13e40 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 ** The first poi
13e50 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 nter (the memory
13e60 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 pointer) must b
13e70 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
13e80 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 8-byte.** bounda
13e90 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 ry or subsequent
13ea0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c behavior of SQL
13eb0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 ite will be unde
13ec0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 fined..** The mi
13ed0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
13ee0 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 size is capped
13ef0 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e at 2**12. Reason
13f00 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 able values.** f
13f10 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 or the minimum a
13f20 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 llocation size a
13f30 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 re 2**5 through
13f40 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 2**8.</dd>.**.**
13f50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
13f60 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c _MUTEX]] <dt>SQL
13f70 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
13f80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
13f90 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
13fa0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 G_MUTEX option t
13fb0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
13fc0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
13fd0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 a.** pointer to
13fe0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
13ff0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
14000 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 x_methods] struc
14010 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 ture..** The arg
14020 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 ument specifies
14030 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
14040 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 level mutex rout
14050 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a ines to be used.
14060 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 ** in place the
14070 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 mutex routines b
14080 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 uilt into SQLite
14090 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b .)^ ^SQLite mak
140a0 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 es a copy of.**
140b0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
140c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
140d0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 x_methods] struc
140e0 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 ture before the
140f0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
14100 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 te3_config()] re
14110 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 turns. ^If SQLit
14120 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
14130 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
14140 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
14150 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
14160 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
14170 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
14180 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 the entire mutex
14190 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 ing subsystem is
141a0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 omitted from th
141b0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 e build and henc
141c0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 e calls to.** [s
141d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
141e0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
141f0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f _CONFIG_MUTEX co
14200 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
14210 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 on will.** retur
14220 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
14230 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
14240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
14250 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 MUTEX]] <dt>SQLI
14260 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
14270 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 EX</dt>.** <dd>
14280 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
14290 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 FIG_GETMUTEX opt
142a0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
142b0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
142c0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 h.** is a pointe
142d0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
142e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
142f0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
14300 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a structure. The.
14310 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 ** [sqlite3_mute
14320 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 x_methods].** st
14330 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 ructure is fille
14340 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 d with the curre
14350 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 ntly defined mut
14360 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a ex routines.)^.*
14370 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 * This option ca
14380 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 n be used to ove
14390 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c rload the defaul
143a0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 t mutex allocati
143b0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 on.** routines w
143c0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 ith a wrapper us
143d0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 ed to track mute
143e0 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 x usage for perf
143f0 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 ormance.** profi
14400 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c ling or testing,
14410 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 for example.
14420 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
14430 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
14440 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
14450 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
14460 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
14470 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
14480 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 then.** the ent
14490 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 ire mutexing sub
144a0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 system is omitte
144b0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 d from the build
144c0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 and hence calls
144d0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
144e0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 config()] with t
144f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
14500 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 _GETMUTEX config
14510 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 uration option w
14520 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 ill.** return [S
14530 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 QLITE_ERROR].</d
14540 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
14550 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
14560 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f DE]] <dt>SQLITE_
14570 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
14580 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
14590 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
145a0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 G_LOOKASIDE opti
145b0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 on takes two arg
145c0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 uments that dete
145d0 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 rmine.** the def
145e0 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f ault size of loo
145f0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e kaside memory on
14600 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 each [database
14610 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 connection]..**
14620 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
14630 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a nt is the.** siz
14640 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 e of each lookas
14650 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 ide buffer slot
14660 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 and the second i
14670 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
14680 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 ** slots allocat
14690 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 ed to each datab
146a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 ase connection.)
146b0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 ^ ^(SQLITE_CONF
146c0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 IG_LOOKASIDE.**
146d0 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 sets the <i>defa
146e0 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 ult</i> lookasid
146f0 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c e size. The [SQL
14700 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
14710 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f KASIDE].** optio
14720 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 n to [sqlite3_db
14730 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 _config()] can b
14740 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 e used to change
14750 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a the lookaside.*
14760 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
14770 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f on individual co
14780 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 nnections.)^ </d
14790 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
147a0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 E_CONFIG_PCACHE2
147b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
147c0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 NFIG_PCACHE2</dt
147d0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 >.** <dd> ^(The
147e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
147f0 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b ACHE2 option tak
14800 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
14810 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a ment which is .*
14820 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * a pointer to a
14830 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 n [sqlite3_pcach
14840 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 e_methods2] obje
14850 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 ct. This object
14860 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 specifies.** th
14870 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 e interface to a
14880 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 custom page cac
14890 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
148a0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 n.)^.** ^SQLite
148b0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
148c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 the [sqlite3_pca
148d0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 che_methods2] ob
148e0 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ject.</dd>.**.**
148f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
14900 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 _GETPCACHE2]] <d
14910 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
14920 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a GETPCACHE2</dt>.
14930 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
14940 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
14950 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 CACHE2 option ta
14960 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
14970 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 ument which.** i
14980 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
14990 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 n [sqlite3_pcach
149a0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 e_methods2] obje
149b0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 ct. SQLite copi
149c0 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 es of.** the cur
149d0 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 rent page cache
149e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
149f0 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e nto that object.
14a00 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b )^ </dd>.**.** [
14a10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c [SQLITE_CONFIG_L
14a20 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f OG]] <dt>SQLITE_
14a30 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a CONFIG_LOG</dt>.
14a40 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 ** <dd> The SQLI
14a50 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 TE_CONFIG_LOG op
14a60 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
14a70 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 configure the SQ
14a80 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b Lite.** global [
14a90 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 error log]..** (
14aa0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
14ab0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 IG_LOG option ta
14ac0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 kes two argument
14ad0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 s: a pointer to
14ae0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 a.** function wi
14af0 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 th a call signat
14b00 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 ure of void(*)(v
14b10 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 oid*,int,const c
14b20 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 har*), .** and a
14b30 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 pointer to void
14b40 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 . ^If the functi
14b50 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f on pointer is no
14b60 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a t NULL, it is.**
14b70 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c invoked by [sql
14b80 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 ite3_log()] to p
14b90 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 rocess each logg
14ba0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 ing event. ^If
14bb0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 the.** function
14bc0 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c pointer is NULL,
14bd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f the [sqlite3_lo
14be0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 g()] interface b
14bf0 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a ecomes a no-op..
14c00 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 ** ^The void poi
14c10 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 nter that is the
14c20 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
14c30 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 to SQLITE_CONFI
14c40 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 G_LOG is.** pass
14c50 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 ed through as th
14c60 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
14c70 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 r to the applica
14c80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 tion-defined log
14c90 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ger.** function
14ca0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 whenever that fu
14cb0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 nction is invoke
14cc0 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 d. ^The second
14cd0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
14ce0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 the logger funct
14cf0 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ion is a copy of
14d00 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
14d10 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 eter to the corr
14d20 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 esponding.** [sq
14d30 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c lite3_log()] cal
14d40 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 l and is intende
14d50 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c d to be a [resul
14d60 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a t code] or an.**
14d70 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
14d80 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 t code]. ^The t
14d90 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 hird parameter p
14da0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 assed to the log
14db0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 ger is.** log me
14dc0 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d ssage after form
14dd0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 atting via [sqli
14de0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e te3_snprintf()].
14df0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c .** The SQLite l
14e00 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 ogging interface
14e10 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e is not reentran
14e20 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 t; the logger fu
14e30 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 nction.** suppli
14e40 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ed by the applic
14e50 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 ation must not i
14e60 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 nvoke any SQLite
14e70 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 interface..** I
14e80 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 n a multi-thread
14e90 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 ed application,
14ea0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
14eb0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a defined logger.*
14ec0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
14ed0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c be threadsafe. <
14ee0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
14ef0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d ITE_CONFIG_URI]]
14f00 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
14f10 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 IG_URI.** <dd>^(
14f20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
14f30 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b G_URI option tak
14f40 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
14f50 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 ment of type int
14f60 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f ..** If non-zero
14f70 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c , then URI handl
14f80 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 ing is globally
14f90 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 enabled. If the
14fa0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 parameter is zer
14fb0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 o,.** then URI h
14fc0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 andling is globa
14fd0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 lly disabled.)^
14fe0 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 ^If URI handling
14ff0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 is globally.**
15000 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c enabled, all fil
15010 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f enames passed to
15020 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
15030 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
15040 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 _v2()],.** [sqli
15050 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 te3_open16()] or
15060 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 .** specified as
15070 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 part of [ATTACH
15080 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 ] commands are i
15090 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 nterpreted as UR
150a0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a Is, regardless.*
150b0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 * of whether or
150c0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f not the [SQLITE_
150d0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 OPEN_URI] flag i
150e0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 s set when the d
150f0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
15100 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e ction is opened.
15110 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 ^If it is globa
15120 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 lly disabled, fi
15130 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f lenames are.** o
15140 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 nly interpreted
15150 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 as URIs if the S
15160 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 QLITE_OPEN_URI f
15170 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 lag is set when
15180 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
15190 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 connection is op
151a0 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 ened. ^(By defau
151b0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 lt, URI handling
151c0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 is globally.**
151d0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 disabled. The de
151e0 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 fault value may
151f0 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f be changed by co
15200 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 mpiling with the
15210 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f .** [SQLITE_USE_
15220 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 URI] symbol defi
15230 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 ned.)^.**.** [[S
15240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 QLITE_CONFIG_COV
15250 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e ERING_INDEX_SCAN
15260 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
15270 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e NFIG_COVERING_IN
15280 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e DEX_SCAN.** <dd>
15290 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
152a0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 IG_COVERING_INDE
152b0 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 X_SCAN option ta
152c0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 kes a single int
152d0 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 eger.** argument
152e0 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 which is interp
152f0 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 reted as a boole
15300 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 an in order to e
15310 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 nable or disable
15320 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 .** the use of c
15330 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 overing indices
15340 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 for full table s
15350 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 cans in the quer
15360 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 y optimizer..**
15370 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 ^The default set
15380 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e ting is determin
15390 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 ed.** by the [SQ
153a0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 LITE_ALLOW_COVER
153b0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 ING_INDEX_SCAN]
153c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
153d0 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a ion, or is "on".
153e0 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 ** if that compi
153f0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 le-time option i
15400 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 s omitted..** Th
15410 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 e ability to dis
15420 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 able the use of
15430 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 covering indices
15440 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 for full table
15450 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 scans.** is beca
15460 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 use some incorre
15470 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 ctly coded legac
15480 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d y applications m
15490 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e ight malfunction
154a0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 .** when the opt
154b0 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 imization is ena
154c0 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 bled. Providing
154d0 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a the ability to.
154e0 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f ** disable the o
154f0 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f ptimization allo
15500 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 ws the older, bu
15510 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 ggy application
15520 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 code to work.**
15530 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 without change e
15540 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 ven with newer v
15550 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
15560 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 e..**.** [[SQLIT
15570 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d E_CONFIG_PCACHE]
15580 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ] [[SQLITE_CONFI
15590 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a G_GETPCACHE]].**
155a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
155b0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 IG_PCACHE and SQ
155c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
155d0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 CACHE.** <dd> Th
155e0 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 ese options are
155f0 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f obsolete and sho
15600 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 uld not be used
15610 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 by new code..**
15620 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 They are retaine
15630 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 d for backwards
15640 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 compatibility bu
15650 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 t are now no-ops
15660 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
15670 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
15680 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 _SQLLOG]].** <dt
15690 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
156a0 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 QLLOG.** <dd>Thi
156b0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 s option is only
156c0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 available if sq
156d0 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 lite is compiled
156e0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
156f0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c LITE_ENABLE_SQLL
15700 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f OG] pre-processo
15710 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e r macro defined.
15720 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
15730 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 ent should.** be
15740 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
15750 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 function of type
15760 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 void(*)(void*,s
15770 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 qlite3*,const ch
15780 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 ar*, int)..** Th
15790 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 e second should
157a0 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 be of type (void
157b0 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b *). The callback
157c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 is invoked by t
157d0 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e he library.** in
157e0 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 three separate
157f0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 circumstances, i
15800 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 dentified by the
15810 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 value passed as
15820 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 the.** fourth p
15830 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 arameter. If the
15840 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
15850 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 r is 0, then the
15860 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
15870 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 tion.** passed a
15880 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
15890 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 ument has just b
158a0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 een opened. The
158b0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a third argument.*
158c0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 * points to a bu
158d0 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ffer containing
158e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
158f0 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 main database fi
15900 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f le. If the.** fo
15910 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
15920 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 s 1, then the SQ
15930 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 L statement that
15940 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
15950 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 eter.** points t
15960 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 o has just been
15970 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 executed. Or, if
15980 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
15990 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e meter is 2, then
159a0 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 .** the connecti
159b0 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 on being passed
159c0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
159d0 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 rameter is being
159e0 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 closed. The.**
159f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
15a00 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 is passed NULL I
15a10 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e n this case. An
15a20 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e example of usin
15a30 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 g this.** config
15a40 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 uration option c
15a50 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 an be seen in th
15a60 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 e "test_sqllog.c
15a70 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e " source file in
15a80 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 .** the canonica
15a90 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 l SQLite source
15aa0 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tree.</dd>.**.**
15ab0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
15ac0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 _MMAP_SIZE]].**
15ad0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
15ae0 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c G_MMAP_SIZE.** <
15af0 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 dd>^SQLITE_CONFI
15b00 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 G_MMAP_SIZE take
15b10 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 s two 64-bit int
15b20 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e eger (sqlite3_in
15b30 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 t64) values.** t
15b40 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 hat are the defa
15b50 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 ult mmap size li
15b60 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 mit (the default
15b70 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 setting for.**
15b80 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a [PRAGMA mmap_siz
15b90 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 e]) and the maxi
15ba0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 mum allowed mmap
15bb0 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 size limit..**
15bc0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 ^The default set
15bd0 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 ting can be over
15be0 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 ridden by each d
15bf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
15c00 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 on using.** eith
15c10 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d er the [PRAGMA m
15c20 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e map_size] comman
15c30 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 d, or by using t
15c40 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 he.** [SQLITE_FC
15c50 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 NTL_MMAP_SIZE] f
15c60 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 ile control. ^(
15c70 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f The maximum allo
15c80 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a wed mmap size.**
15c90 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c will be silentl
15ca0 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e y truncated if n
15cb0 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 ecessary so that
15cc0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 it does not exc
15cd0 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 eed the.** compi
15ce0 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 le-time maximum
15cf0 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 mmap size set by
15d00 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
15d10 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 MAX_MMAP_SIZE] c
15d20 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
15d30 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 on.)^.** ^If eit
15d40 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 her argument to
15d50 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e this option is n
15d60 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 egative, then th
15d70 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a at argument is.*
15d80 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 * changed to its
15d90 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 compile-time de
15da0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 fault..**.** [[S
15db0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e QLITE_CONFIG_WIN
15dc0 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 32_HEAPSIZE]].**
15dd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
15de0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a IG_WIN32_HEAPSIZ
15df0 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 E.** <dd>^The SQ
15e00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 LITE_CONFIG_WIN3
15e10 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 2_HEAPSIZE optio
15e20 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 n is only availa
15e30 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 ble if SQLite is
15e40 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 .** compiled for
15e50 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 Windows with th
15e60 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f e [SQLITE_WIN32_
15e70 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 MALLOC] pre-proc
15e80 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 essor macro.** d
15e90 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f efined. ^SQLITE_
15ea0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 CONFIG_WIN32_HEA
15eb0 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 PSIZE takes a 32
15ec0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e -bit unsigned in
15ed0 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 teger value.** t
15ee0 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 hat specifies th
15ef0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f e maximum size o
15f00 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 f the created he
15f10 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 ap..**.** [[SQLI
15f20 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
15f30 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e _HDRSZ]].** <dt>
15f40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
15f50 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 ACHE_HDRSZ.** <d
15f60 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d>^The SQLITE_CO
15f70 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 NFIG_PCACHE_HDRS
15f80 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 Z option takes a
15f90 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 single paramete
15fa0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 r which.** is a
15fb0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
15fc0 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 teger and writes
15fd0 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 into that integ
15fe0 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 er the number of
15ff0 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 extra.** bytes
16000 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 per page require
16010 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 d for each page
16020 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 in [SQLITE_CONFI
16030 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a G_PAGECACHE]..**
16040 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 The amount of e
16050 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 xtra space requi
16060 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 red can change d
16070 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
16080 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 compiler,.** tar
16090 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e get platform, an
160a0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e d SQLite version
160b0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ..**.** [[SQLITE
160c0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a _CONFIG_PMASZ]].
160d0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
160e0 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 NFIG_PMASZ.** <d
160f0 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d>^The SQLITE_CO
16100 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f NFIG_PMASZ optio
16110 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
16120 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 parameter which
16130 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e .** is an unsign
16140 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 ed integer and s
16150 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d ets the "Minimum
16160 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 PMA Size" for t
16170 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 he multithreaded
16180 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 .** sorter to th
16190 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 at integer. The
161a0 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d default minimum
161b0 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 PMA Size is set
161c0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 by the.** [SQLI
161d0 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d TE_SORTER_PMASZ]
161e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
161f0 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 tion. New threa
16200 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a ds are launched.
16210 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 ** to help with
16220 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 sort operations
16230 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 when multithread
16240 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 ed sorting.** is
16250 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 enabled (using
16260 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 the [PRAGMA thre
16270 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e ads] command) an
16280 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 d the amount of
16290 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 content.** to be
162a0 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 sorted exceeds
162b0 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 the page size ti
162c0 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 mes the minimum
162d0 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d of the.** [PRAGM
162e0 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 A cache_size] se
162f0 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 tting and this v
16300 61 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a alue..** </dl>.*
16310 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16320 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
16330 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 READ 1 /* nil
16340 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16350 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
16360 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c READ 2 /* nil
16370 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16380 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
16390 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 IZED 3 /* ni
163a0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
163b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
163c0 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 C 4 /* s
163d0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
163e0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
163f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
16400 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a MALLOC 5 /*
16410 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
16420 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
16430 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
16440 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 CRATCH 6
16450 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a /* void*, int sz
16460 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 , int N */.#defi
16470 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16480 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 _PAGECACHE 7
16490 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
164a0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 sz, int N */.#de
164b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
164c0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 IG_HEAP
164d0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 8 /* void*, in
164e0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e t nByte, int min
164f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16500 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
16510 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f TUS 9 /* bo
16520 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 olean */.#define
16530 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
16540 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 UTEX 10
16550 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 /* sqlite3_mutex
16560 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
16570 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16580 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 IG_GETMUTEX
16590 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 11 /* sqlite3_m
165a0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f utex_methods* */
165b0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 ./* previously S
165c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 QLITE_CONFIG_CHU
165d0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 NKALLOC 12 which
165e0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 is now unused.
165f0 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */ .#define SQLI
16600 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
16610 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e IDE 13 /* in
16620 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 t int */.#define
16630 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
16640 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 CACHE 14
16650 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 /* no-op */.#def
16660 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
16670 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 G_GETPCACHE 1
16680 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 5 /* no-op */.#
16690 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
166a0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 NFIG_LOG
166b0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 16 /* xFunc,
166c0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 void* */.#define
166d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 SQLITE_CONFIG_U
166e0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 RI 17
166f0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e /* int */.#defin
16700 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16710 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 PCACHE2 18
16720 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 /* sqlite3_pcac
16730 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a he_methods2* */.
16740 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16750 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
16760 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 19 /* sqlite
16770 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
16780 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 2* */.#define SQ
16790 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 LITE_CONFIG_COVE
167a0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 RING_INDEX_SCAN
167b0 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 20 /* int */.#d
167c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
167d0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 FIG_SQLLOG
167e0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 21 /* xSqllog,
167f0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e void* */.#defin
16800 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16810 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 MMAP_SIZE 22
16820 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 /* sqlite3_int6
16830 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 4, sqlite3_int64
16840 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16850 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f TE_CONFIG_WIN32_
16860 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 HEAPSIZE 23
16870 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a /* int nByte *
16880 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16890 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 _CONFIG_PCACHE_H
168a0 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 DRSZ 24
168b0 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 /* int *psz */.#
168c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
168d0 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 NFIG_PMASZ
168e0 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 25 /*
168f0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 unsigned int szP
16900 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ma */../*.** CAP
16910 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
16920 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 Connection Confi
16930 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 guration Options
16940 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
16950 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 stants are the a
16960 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 vailable integer
16970 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
16980 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 ptions that.** c
16990 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 an be passed as
169a0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
169b0 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ent to the [sqli
169c0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
169d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
169e0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 * New configurat
169f0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 ion options may
16a00 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
16a10 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
16a20 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 QLite..** Existi
16a30 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ng configuration
16a40 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 options might b
16a50 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 e discontinued.
16a60 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a Applications.**
16a70 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 should check th
16a80 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 e return code fr
16a90 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 om [sqlite3_db_c
16aa0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 onfig()] to make
16ab0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 sure that.** th
16ac0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 e call worked.
16ad0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 ^The [sqlite3_db
16ae0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
16af0 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e face will return
16b00 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b a.** non-zero [
16b10 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 error code] if a
16b20 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 discontinued or
16b30 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e unsupported con
16b40 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
16b50 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e n.** is invoked.
16b60 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c .**.** <dl>.** <
16b70 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
16b80 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 IG_LOOKASIDE</dt
16b90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
16ba0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 option takes thr
16bb0 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 ee additional ar
16bc0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 guments that det
16bd0 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b ermine the .** [
16be0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
16bf0 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 allocator] conf
16c00 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 iguration for th
16c10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
16c20 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 ection]..** ^The
16c30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
16c40 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d (the third param
16c50 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
16c60 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 _db_config()] is
16c70 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f a.** pointer to
16c80 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 a memory buffer
16c90 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b to use for look
16ca0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a aside memory..**
16cb0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
16cc0 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 ment after the S
16cd0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
16ce0 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a OOKASIDE verb.**
16cf0 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 may be NULL in
16d00 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 which case SQLit
16d10 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 e will allocate
16d20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 the.** lookaside
16d30 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 buffer itself u
16d40 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 sing [sqlite3_ma
16d50 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 lloc()]. ^The se
16d60 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
16d70 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 the.** size of
16d80 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 each lookaside b
16d90 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 uffer slot. ^Th
16da0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
16db0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
16dc0 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 f.** slots. The
16dd0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 size of the buf
16de0 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 fer in the first
16df0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 argument must b
16e00 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a e greater than.*
16e10 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 * or equal to th
16e20 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 e product of the
16e30 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 second and thir
16e40 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 d arguments. Th
16e50 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 e buffer.** must
16e60 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 be aligned to a
16e70 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 n 8-byte boundar
16e80 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f y. ^If the seco
16e90 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a nd argument to.*
16ea0 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 * SQLITE_DBCONFI
16eb0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e G_LOOKASIDE is n
16ec0 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 ot a multiple of
16ed0 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 8, it is intern
16ee0 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 ally.** rounded
16ef0 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 down to the next
16f00 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c smaller multipl
16f10 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c e of 8. ^(The l
16f20 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a ookaside memory.
16f30 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
16f40 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 for a database
16f50 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f connection can o
16f60 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 nly be changed w
16f70 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e hen that.** conn
16f80 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 ection is not cu
16f90 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f rrently using lo
16fa0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 okaside memory,
16fb0 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 or in other word
16fc0 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 s.** when the "c
16fd0 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 urrent value" re
16fe0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 turned by.** [sq
16ff0 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d lite3_db_status]
17000 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 (D,[SQLITE_CONFI
17010 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e G_LOOKASIDE],...
17020 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e ) is zero..** An
17030 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 y attempt to cha
17040 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 nge the lookasid
17050 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 e memory configu
17060 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b ration when look
17070 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 aside.** memory
17080 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 is in use leaves
17090 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
170a0 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 on unchanged and
170b0 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 returns .** [SQ
170c0 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 LITE_BUSY].)^</d
170d0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
170e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
170f0 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a BLE_FKEY</dt>.**
17100 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
17110 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e on is used to en
17120 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 able or disable
17130 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 the enforcement
17140 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b of.** [foreign k
17150 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e ey constraints].
17160 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 There should b
17170 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c e two additional
17180 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 arguments..** T
17190 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
171a0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 t is an integer
171b0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 which is 0 to di
171c0 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 sable FK enforce
171d0 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 ment,.** positiv
171e0 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 e to enable FK e
171f0 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 nforcement or ne
17200 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 gative to leave
17210 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a FK enforcement.*
17220 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 * unchanged. Th
17230 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
17240 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
17250 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e to an integer in
17260 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 to which.** is w
17270 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f ritten 0 or 1 to
17280 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 indicate whethe
17290 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 r FK enforcement
172a0 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a is off or on.**
172b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 following this
172c0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e call. The secon
172d0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 d parameter may
172e0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 be a NULL pointe
172f0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 r, in.** which c
17300 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 ase the FK enfor
17310 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 cement setting i
17320 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 s not reported b
17330 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ack. </dd>.**.**
17340 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
17350 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 NFIG_ENABLE_TRIG
17360 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GER</dt>.** <dd>
17370 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 ^This option is
17380 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 used to enable
17390 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 or disable [CREA
173a0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 TE TRIGGER | tri
173b0 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 ggers]..** There
173c0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 should be two a
173d0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
173e0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 nts..** The firs
173f0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e t argument is an
17400 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 integer which i
17410 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 s 0 to disable t
17420 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 riggers,.** posi
17430 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 tive to enable t
17440 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 riggers or negat
17450 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 ive to leave the
17460 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 setting unchang
17470 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e ed..** The secon
17480 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 d parameter is a
17490 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
174a0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 nteger into whic
174b0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 h.** is written
174c0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 0 or 1 to indica
174d0 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 te whether trigg
174e0 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 ers are disabled
174f0 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 or enabled.** f
17500 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 ollowing this ca
17510 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ll. The second
17520 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
17530 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
17540 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 in.** which cas
17550 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 e the trigger se
17560 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 tting is not rep
17570 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 orted back. </dd
17580 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f >.**.** </dl>.*/
17590 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
175a0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
175b0 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f DE 1001 /
175c0 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 * void* int int
175d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
175e0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
175f0 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 E_FKEY 1002
17600 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a /* int int* */.
17610 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
17620 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 BCONFIG_ENABLE_T
17630 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a RIGGER 1003 /*
17640 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f int int* */.../
17650 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
17660 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 nable Or Disable
17670 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 Extended Result
17680 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 Codes.** METHOD
17690 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
176a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 ^The sqlite3_ext
176b0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
176c0 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 es() routine ena
176d0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 bles or disables
176e0 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 the.** [extende
176f0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 d result codes]
17700 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 feature of SQLit
17710 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 e. ^The extended
17720 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 result.** codes
17730 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 are disabled by
17740 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 default for his
17750 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 torical compatib
17760 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ility..*/.int sq
17770 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 lite3_extended_r
17780 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 esult_codes(sqli
17790 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 te3*, int onoff)
177a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
177b0 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 F: Last Insert R
177c0 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 owid.** METHOD:
177d0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 sqlite3.**.** ^E
177e0 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 ach entry in mos
177f0 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 t SQLite tables
17800 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 (except for [WIT
17810 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c HOUT ROWID] tabl
17820 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 es).** has a uni
17830 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 que 64-bit signe
17840 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 d.** integer key
17850 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 called the [ROW
17860 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e ID | "rowid"]. ^
17870 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 The rowid is alw
17880 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a ays available.**
17890 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 as an undeclare
178a0 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 d column named R
178b0 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 OWID, OID, or _R
178c0 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 OWID_ as long as
178d0 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 those.** names
178e0 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 are not also use
178f0 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 d by explicitly
17900 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 declared columns
17910 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 . ^If.** the tab
17920 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 le has a column
17930 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 of type [INTEGER
17940 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 PRIMARY KEY] th
17950 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a en that column.*
17960 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 * is another ali
17970 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 as for the rowid
17980 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
17990 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
179a0 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 _rowid(D) interf
179b0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
179c0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a [rowid] of the .
179d0 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 ** most recent s
179e0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
179f0 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 T] into a rowid
17a00 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 table or [virtua
17a10 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 l table].** on d
17a20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
17a30 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 on D..** ^Insert
17a40 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 s into [WITHOUT
17a50 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 ROWID] tables ar
17a60 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a e not recorded..
17a70 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 ** ^If no succes
17a80 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 sful [INSERT]s i
17a90 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 nto rowid tables
17aa0 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 .** have ever oc
17ab0 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 curred on the da
17ac0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
17ad0 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 n D, .** then sq
17ae0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
17af0 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 t_rowid(D) retur
17b00 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e ns zero..**.** ^
17b10 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 (If an [INSERT]
17b20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 occurs within a
17b30 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 trigger or withi
17b40 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 n a [virtual tab
17b50 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 le].** method, t
17b60 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 hen this routine
17b70 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 will return the
17b80 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 [rowid] of the
17b90 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 inserted.** row
17ba0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 as long as the t
17bb0 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 rigger or virtua
17bc0 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 l table method i
17bd0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 s running..** Bu
17be0 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 t once the trigg
17bf0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 er or virtual ta
17c00 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c ble method ends,
17c10 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
17c20 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 ned .** by this
17c30 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 routine reverts
17c40 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 to what it was b
17c50 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 efore the trigge
17c60 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 r or virtual.**
17c70 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 table method beg
17c80 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 an.)^.**.** ^An
17c90 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 [INSERT] that fa
17ca0 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e ils due to a con
17cb0 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f straint violatio
17cc0 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 n is not a.** su
17cd0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
17ce0 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 ] and does not c
17cf0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 hange the value
17d00 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 returned by this
17d10 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 .** routine. ^T
17d20 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 hus INSERT OR FA
17d30 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 IL, INSERT OR IG
17d40 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 NORE, INSERT OR
17d50 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 ROLLBACK,.** and
17d60 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 INSERT OR ABORT
17d70 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 make no changes
17d80 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 to the return v
17d90 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 alue of this.**
17da0 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 routine when the
17db0 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 ir insertion fai
17dc0 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 ls. ^(When INSE
17dd0 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a RT OR REPLACE.**
17de0 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f encounters a co
17df0 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
17e00 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 on, it does not
17e10 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e fail. The.** IN
17e20 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 SERT continues t
17e30 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 o completion aft
17e40 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 er deleting rows
17e50 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 that caused.**
17e60 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 the constraint p
17e70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 roblem so INSERT
17e80 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c OR REPLACE will
17e90 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a always change.*
17ea0 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c * the return val
17eb0 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 ue of this inter
17ec0 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 face.)^.**.** ^F
17ed0 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 or the purposes
17ee0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c of this routine,
17ef0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 an [INSERT] is
17f00 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a considered to.**
17f10 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 be successful e
17f20 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 ven if it is sub
17f30 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 sequently rolled
17f40 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 back..**.** Thi
17f50 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 s function is ac
17f60 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 cessible to SQL
17f70 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 statements via t
17f80 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 he.** [last_inse
17f90 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 rt_rowid() SQL f
17fa0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
17fb0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
17fc0 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 read performs a
17fd0 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 new [INSERT] on
17fe0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 the same.** data
17ff0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
18000 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 while the [sqlit
18010 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
18020 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 owid()].** funct
18030 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 ion is running a
18040 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 nd thus changes
18050 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 the last insert
18060 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e [rowid],.** then
18070 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
18080 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
18090 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
180a0 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 d()] is.** unpre
180b0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 dictable and mig
180c0 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 ht not equal eit
180d0 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 her the old or t
180e0 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 he new.** last i
180f0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a nsert [rowid]..*
18100 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 /.sqlite3_int64
18110 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
18120 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 ert_rowid(sqlite
18130 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
18140 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 3REF: Count The
18150 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d Number Of Rows M
18160 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f odified.** METHO
18170 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
18180 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 ^This function
18190 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
181a0 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 er of rows modif
181b0 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 ied, inserted or
181c0 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 .** deleted by t
181d0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 he most recently
181e0 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 completed INSER
181f0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c T, UPDATE or DEL
18200 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 ETE.** statement
18210 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 on the database
18220 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 connection spec
18230 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c ified by the onl
18240 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 y parameter..**
18250 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f ^Executing any o
18260 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c ther type of SQL
18270 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 statement does
18280 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 not modify the v
18290 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 alue.** returned
182a0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f by this functio
182b0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 n..**.** ^Only c
182c0 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 hanges made dire
182d0 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 ctly by the INSE
182e0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 RT, UPDATE or DE
182f0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 LETE statement a
18300 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 re.** considered
18310 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 - auxiliary cha
18320 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b nges caused by [
18330 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c CREATE TRIGGER |
18340 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 triggers], .**
18350 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 [foreign key act
18360 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 ions] or [REPLAC
18370 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 E] constraint re
18380 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 solution are not
18390 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a counted..** .**
183a0 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 Changes to a vi
183b0 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 ew that are inte
183c0 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b rcepted by .** [
183d0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 INSTEAD OF trigg
183e0 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 er | INSTEAD OF
183f0 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f triggers] are no
18400 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 t counted. ^The
18410 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e value .** return
18420 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 ed by sqlite3_ch
18430 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 anges() immediat
18440 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 ely after an INS
18450 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a ERT, UPDATE or .
18460 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d ** DELETE statem
18470 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 ent run on a vie
18480 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f w is always zero
18490 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d . Only changes m
184a0 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 ade to real .**
184b0 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 tables are count
184c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 ed..**.** Things
184d0 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 are more compli
184e0 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c cated if the sql
184f0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 ite3_changes() f
18500 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 unction is.** ex
18510 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 ecuted while a t
18520 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 rigger program i
18530 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 s running. This
18540 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 may happen if th
18550 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 e.** program use
18560 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 s the [changes()
18570 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 SQL function],
18580 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 or if some other
18590 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e callback.** fun
185a0 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 ction invokes sq
185b0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
185c0 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 directly. Essent
185d0 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 ially:.** .** <u
185e0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 l>.** <li> ^(B
185f0 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 efore entering a
18600 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d trigger program
18610 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
18620 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 ned by.**
18630 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
18640 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 () function is s
18650 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 aved. After the
18660 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 trigger program
18670 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 .** has f
18680 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 inished, the ori
18690 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 ginal value is r
186a0 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a estored.)^.** .*
186b0 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 * <li> ^(Withi
186c0 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 n a trigger prog
186d0 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c ram each INSERT,
186e0 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 UPDATE and DELE
186f0 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 TE .** st
18700 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 atement sets the
18710 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
18720 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 by sqlite3_chang
18730 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 es() .**
18740 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 upon completion
18750 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f as normal. Of co
18760 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 urse, this value
18770 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 will not includ
18780 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 e .** any
18790 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d changes perform
187a0 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 ed by sub-trigge
187b0 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 rs, as the sqlit
187c0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a e3_changes() .**
187d0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 value wi
187e0 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 ll be saved and
187f0 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 restored after e
18800 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 ach sub-trigger
18810 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f has run.)^.** </
18820 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 ul>.** .** ^This
18830 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 means that if t
18840 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c he changes() SQL
18850 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 function (or si
18860 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a milar) is used.*
18870 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 * by the first I
18880 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 NSERT, UPDATE or
18890 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
188a0 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 t within a trigg
188b0 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 er, it .** retur
188c0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 ns the value as
188d0 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c set when the cal
188e0 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 ling statement b
188f0 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a egan executing..
18900 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 ** ^If it is use
18910 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 d by the second
18920 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 or subsequent su
18930 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 ch statement wit
18940 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a hin a trigger .*
18950 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 * program, the v
18960 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 alue returned re
18970 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 flects the numbe
18980 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 r of rows modifi
18990 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 ed by the .** pr
189a0 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 evious INSERT, U
189b0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 PDATE or DELETE
189c0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e statement within
189d0 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 the same trigge
189e0 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 r..**.** See als
189f0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 o the [sqlite3_t
18a00 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 otal_changes()]
18a10 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a interface, the.*
18a20 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 * [count_changes
18a30 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 pragma], and th
18a40 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c e [changes() SQL
18a50 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a function]..**.*
18a60 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 * If a separate
18a70 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 thread makes cha
18a80 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 nges on the same
18a90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
18aa0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 tion.** while [s
18ab0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
18ac0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 ] is running the
18ad0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 n the value retu
18ae0 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 rned.** is unpre
18af0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 dictable and not
18b00 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a meaningful..*/.
18b10 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e int sqlite3_chan
18b20 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a ges(sqlite3*);..
18b30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
18b40 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 Total Number Of
18b50 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a Rows Modified.**
18b60 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
18b70 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .**.** ^This fun
18b80 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
18b90 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f e total number o
18ba0 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c f rows inserted,
18bb0 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 modified or.**
18bc0 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b deleted by all [
18bd0 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 INSERT], [UPDATE
18be0 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 ] or [DELETE] st
18bf0 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 atements complet
18c00 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 ed.** since the
18c10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18c20 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 ion was opened,
18c30 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 including those
18c40 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 executed as.** p
18c50 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 art of trigger p
18c60 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 rograms. ^Execut
18c70 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 ing any other ty
18c80 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d pe of SQL statem
18c90 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 ent.** does not
18ca0 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 affect the value
18cb0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
18cc0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
18cd0 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 es()..** .** ^Ch
18ce0 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 anges made as pa
18cf0 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b rt of [foreign k
18d00 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 ey actions] are
18d10 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a included in the.
18d20 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 ** count, but th
18d30 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 ose made as part
18d40 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 of REPLACE cons
18d50 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f traint resolutio
18d60 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 n are.** not. ^C
18d70 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 hanges to a view
18d80 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 that are interc
18d90 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 epted by INSTEAD
18da0 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a OF triggers .**
18db0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
18dc0 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 ..** .** See als
18dd0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 o the [sqlite3_c
18de0 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 hanges()] interf
18df0 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 ace, the.** [cou
18e00 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d nt_changes pragm
18e10 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 a], and the [tot
18e20 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c al_changes() SQL
18e30 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a function]..**.*
18e40 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 * If a separate
18e50 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 thread makes cha
18e60 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 nges on the same
18e70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
18e80 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 tion.** while [s
18e90 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
18ea0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 nges()] is runni
18eb0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 ng then the valu
18ec0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 e.** returned is
18ed0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 unpredictable a
18ee0 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 nd not meaningfu
18ef0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 l..*/.int sqlite
18f00 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
18f10 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
18f20 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 * CAPI3REF: Inte
18f30 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e rrupt A Long-Run
18f40 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 ning Query.** ME
18f50 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
18f60 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
18f70 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 on causes any pe
18f80 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f nding database o
18f90 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 peration to abor
18fa0 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 t and.** return
18fb0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 at its earliest
18fc0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 opportunity. Thi
18fd0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 s routine is typ
18fe0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 ically.** called
18ff0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 in response to
19000 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 a user action su
19010 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 ch as pressing "
19020 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 Cancel".** or Ct
19030 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 rl-C where the u
19040 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 ser wants a long
19050 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e query operation
19060 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 to halt.** imme
19070 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e diately..**.** ^
19080 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 It is safe to ca
19090 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ll this routine
190a0 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 from a thread di
190b0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 fferent from the
190c0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 .** thread that
190d0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e is currently run
190e0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 ning the databas
190f0 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 e operation. Bu
19100 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 t it.** is not s
19110 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 afe to call this
19120 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 routine with a
19130 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
19140 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 tion] that.** is
19150 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 closed or might
19160 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 close before sq
19170 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
19180 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a ) returns..**.**
19190 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 ^If an SQL oper
191a0 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 ation is very ne
191b0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 arly finished at
191c0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a the time when.*
191d0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 * sqlite3_interr
191e0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c upt() is called,
191f0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e then it might n
19200 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 ot have an oppor
19210 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 tunity.** to be
19220 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 interrupted and
19230 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 might continue t
19240 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a o completion..**
19250 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 .** ^An SQL oper
19260 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e ation that is in
19270 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 terrupted will r
19280 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e eturn [SQLITE_IN
19290 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 TERRUPT]..** ^If
192a0 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 the interrupted
192b0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 SQL operation i
192c0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 s an INSERT, UPD
192d0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a ATE, or DELETE.*
192e0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 * that is inside
192f0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 an explicit tra
19300 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 nsaction, then t
19310 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 he entire transa
19320 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 ction.** will be
19330 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 rolled back aut
19340 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a omatically..**.*
19350 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
19360 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c nterrupt(D) call
19370 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e is in effect un
19380 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c til all currentl
19390 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c y running.** SQL
193a0 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b statements on [
193b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
193c0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e ion] D complete.
193d0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 ^Any new SQL s
193e0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
193f0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
19400 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f ter the sqlite3_
19410 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c interrupt() call
19420 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 and before the
19430 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 .** running stat
19440 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a ements reaches z
19450 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 ero are interrup
19460 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 ted as if they h
19470 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 ad been.** runni
19480 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 ng prior to the
19490 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
194a0 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 t() call. ^New
194b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
194c0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 * that are start
194d0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e ed after the run
194e0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 ning statement c
194f0 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 ount reaches zer
19500 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 o are.** not eff
19510 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c ected by the sql
19520 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
19530 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 ..** ^A call to
19540 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
19550 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 t(D) that occurs
19560 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 when there are
19570 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 no running.** SQ
19580 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 L statements is
19590 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 a no-op and has
195a0 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c no effect on SQL
195b0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 statements.** t
195c0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 hat are started
195d0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 after the sqlite
195e0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
195f0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a ll returns..**.*
19600 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 * If the databas
19610 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f e connection clo
19620 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 ses while [sqlit
19630 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a e3_interrupt()].
19640 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 ** is running th
19650 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 en bad things wi
19660 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e ll likely happen
19670 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
19680 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 3_interrupt(sqli
19690 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
196a0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e PI3REF: Determin
196b0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 e If An SQL Stat
196c0 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 ement Is Complet
196d0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f e.**.** These ro
196e0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 utines are usefu
196f0 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 l during command
19700 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 -line input to d
19710 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a etermine if the.
19720 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 ** currently ent
19730 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 ered text seems
19740 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 to form a comple
19750 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 te SQL statement
19760 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 or.** if additi
19770 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 onal input is ne
19780 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 eded before send
19790 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 ing the text int
197a0 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 o.** SQLite for
197b0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 parsing. ^These
197c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
197d0 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 1 if the input
197e0 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 string.** appear
197f0 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 s to be a comple
19800 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 te SQL statement
19810 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 . ^A statement
19820 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a is judged to be.
19830 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 ** complete if i
19840 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 t ends with a se
19850 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e micolon token an
19860 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 d is not a prefi
19870 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 x of a.** well-f
19880 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 ormed CREATE TRI
19890 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 GGER statement.
198a0 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 ^Semicolons tha
198b0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 t are embedded w
198c0 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 ithin.** string
198d0 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 literals or quot
198e0 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 ed identifier na
198f0 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 mes or comments
19900 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 are not.** indep
19910 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 endent tokens (t
19920 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 hey are part of
19930 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 the token in whi
19940 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 ch they are.** e
19950 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 mbedded) and thu
19960 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 s do not count a
19970 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 s a statement te
19980 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 rminator. ^Whit
19990 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f espace.** and co
199a0 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c mments that foll
199b0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d ow the final sem
199c0 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 icolon are ignor
199d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 ed..**.** ^These
199e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
199f0 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 0 if the statem
19a00 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 ent is incomplet
19a10 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d e. ^If a.** mem
19a20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
19a30 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 ails, then SQLIT
19a40 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 E_NOMEM is retur
19a50 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ned..**.** ^Thes
19a60 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f e routines do no
19a70 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 t parse the SQL
19a80 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a statements thus.
19a90 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 ** will not dete
19aa0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 ct syntactically
19ab0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a incorrect SQL..
19ac0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 **.** ^(If SQLit
19ad0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 e has not been i
19ae0 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 nitialized using
19af0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
19b00 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a lize()] prior .*
19b10 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 * to invoking sq
19b20 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
19b30 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f () then sqlite3_
19b40 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
19b50 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d invoked.** autom
19b60 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 atically by sqli
19b70 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
19b80 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 . If that initi
19b90 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c alization fails,
19ba0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 .** then the ret
19bb0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 urn value from s
19bc0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
19bd0 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 6() will be non-
19be0 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 zero.** regardle
19bf0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
19c00 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 not the input S
19c10 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 QL is complete.)
19c20 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 ^.**.** The inpu
19c30 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
19c40 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 mplete()] must b
19c50 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 e a zero-termina
19c60 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 ted.** UTF-8 str
19c70 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ing..**.** The i
19c80 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 nput to [sqlite3
19c90 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d _complete16()] m
19ca0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 ust be a zero-te
19cb0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d rminated.** UTF-
19cc0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 16 string in nat
19cd0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a ive byte order..
19ce0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
19cf0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 omplete(const ch
19d00 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 ar *sql);.int sq
19d10 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
19d20 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c (const void *sql
19d30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
19d40 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 EF: Register A C
19d50 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c allback To Handl
19d60 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 e SQLITE_BUSY Er
19d70 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 rors.** KEYWORDS
19d80 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 : {busy-handler
19d90 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 callback} {busy
19da0 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 handler}.** METH
19db0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
19dc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 * ^The sqlite3_b
19dd0 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c usy_handler(D,X,
19de0 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 P) routine sets
19df0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
19e00 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 ion X.** that mi
19e10 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 ght be invoked w
19e20 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 ith argument P w
19e30 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 henever.** an at
19e40 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f tempt is made to
19e50 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 access a databa
19e60 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 se table associa
19e70 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 ted with.** [dat
19e80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
19e90 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 ] D when another
19ea0 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 thread.** or pr
19eb0 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 ocess has the ta
19ec0 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 ble locked..** T
19ed0 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f he sqlite3_busy_
19ee0 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 handler() interf
19ef0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 ace is used to i
19f00 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c mplement.** [sql
19f10 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
19f20 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 t()] and [PRAGMA
19f30 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a busy_timeout]..
19f40 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 **.** ^If the bu
19f50 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e sy callback is N
19f60 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 ULL, then [SQLIT
19f70 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 E_BUSY].** is re
19f80 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 turned immediate
19f90 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 ly upon encounte
19fa0 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 ring the lock.
19fb0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c ^If the busy cal
19fc0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 lback.** is not
19fd0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 NULL, then the c
19fe0 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 allback might be
19ff0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 invoked with tw
1a000 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a o arguments..**.
1a010 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
1a020 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 gument to the bu
1a030 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 sy handler is a
1a040 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 copy of the void
1a050 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a * pointer which.
1a060 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 ** is the third
1a070 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
1a080 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
1a090 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 (). ^The second
1a0a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
1a0b0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
1a0c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 callback is the
1a0d0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 number of times
1a0e0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 that the busy h
1a0f0 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 andler has.** be
1a100 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 en invoked previ
1a110 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 ously for the sa
1a120 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 me locking event
1a130 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 . ^If the.** bu
1a140 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 sy callback retu
1a150 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 rns 0, then no a
1a160 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 dditional attemp
1a170 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a ts are made to.*
1a180 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 * access the dat
1a190 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 abase and [SQLIT
1a1a0 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 E_BUSY] is retur
1a1b0 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 ned.** to the ap
1a1c0 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 plication..** ^I
1a1d0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 f the callback r
1a1e0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
1a1f0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 then another at
1a200 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 tempt.** is made
1a210 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 to access the d
1a220 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 atabase and the
1a230 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a cycle repeats..*
1a240 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 *.** The presenc
1a250 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 e of a busy hand
1a260 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 ler does not gua
1a270 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 rantee that it w
1a280 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a ill be invoked.*
1a290 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 * when there is
1a2a0 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e lock contention.
1a2b0 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 ^If SQLite dete
1a2c0 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f rmines that invo
1a2d0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a king the busy.**
1a2e0 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 handler could r
1a2f0 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c esult in a deadl
1a300 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 ock, it will go
1a310 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e ahead and return
1a320 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a [SQLITE_BUSY].*
1a330 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 * to the applica
1a340 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 tion instead of
1a350 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a invoking the .**
1a360 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
1a370 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 * Consider a sce
1a380 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 nario where one
1a390 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 process is holdi
1a3a0 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 ng a read lock t
1a3b0 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 hat.** it is try
1a3c0 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 ing to promote t
1a3d0 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 o a reserved loc
1a3e0 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e k and.** a secon
1a3f0 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c d process is hol
1a400 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 ding a reserved
1a410 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 lock that it is
1a420 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f trying.** to pro
1a430 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 mote to an exclu
1a440 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 sive lock. The
1a450 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 first process ca
1a460 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 nnot proceed.**
1a470 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c because it is bl
1a480 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 ocked by the sec
1a490 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f ond and the seco
1a4a0 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f nd process canno
1a4b0 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 t.** proceed bec
1a4c0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
1a4d0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e ed by the first.
1a4e0 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 If both proces
1a4f0 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 ses.** invoke th
1a500 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c e busy handlers,
1a510 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 neither will ma
1a520 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e ke any progress.
1a530 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 Therefore,.**
1a540 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b SQLite returns [
1a550 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 SQLITE_BUSY] for
1a560 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
1a570 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 ss, hoping that
1a580 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 this.** will ind
1a590 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 uce the first pr
1a5a0 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 ocess to release
1a5b0 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 its read lock a
1a5c0 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 nd allow.** the
1a5d0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 second process t
1a5e0 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a o proceed..**.**
1a5f0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 ^The default bu
1a600 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e sy callback is N
1a610 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ULL..**.** ^(The
1a620 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 re can only be a
1a630 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e single busy han
1a640 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 dler defined for
1a650 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 each.** [databa
1a660 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
1a670 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 Setting a new b
1a680 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 usy handler clea
1a690 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f rs any.** previo
1a6a0 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 usly set handler
1a6b0 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 .)^ ^Note that
1a6c0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
1a6d0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d _busy_timeout()]
1a6e0 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e .** or evaluatin
1a6f0 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 g [PRAGMA busy_t
1a700 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 imeout=N] will c
1a710 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 hange the.** bus
1a720 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 y handler and th
1a730 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 us clear any pre
1a740 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 viously set busy
1a750 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 handler..**.**
1a760 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 The busy callbac
1a770 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b k should not tak
1a780 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 e any actions wh
1a790 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a ich modify the.*
1a7a0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
1a7b0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b ction that invok
1a7c0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ed the busy hand
1a7d0 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 ler. In other w
1a7e0 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 ords,.** the bus
1a7f0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 y handler is not
1a800 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 reentrant. Any
1a810 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a such actions.**
1a820 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 result in undef
1a830 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a ined behavior..*
1a840 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e * .** A busy han
1a850 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c dler must not cl
1a860 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ose the database
1a870 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f connection.** o
1a880 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 r [prepared stat
1a890 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f ement] that invo
1a8a0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e ked the busy han
1a8b0 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c dler..*/.int sql
1a8c0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
1a8d0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 r(sqlite3*, int(
1a8e0 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 *)(void*,int), v
1a8f0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
1a900 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 PI3REF: Set A Bu
1a910 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 sy Timeout.** ME
1a920 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
1a930 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
1a940 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 e sets a [sqlite
1a950 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 3_busy_handler |
1a960 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 busy handler] t
1a970 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f hat sleeps.** fo
1a980 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d r a specified am
1a990 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 ount of time whe
1a9a0 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 n a table is loc
1a9b0 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c ked. ^The handl
1a9c0 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 er.** will sleep
1a9d0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
1a9e0 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 until at least "
1a9f0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 ms" milliseconds
1aa00 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 of sleeping.**
1aa10 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 have accumulated
1aa20 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 . ^After at lea
1aa30 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 st "ms" millisec
1aa40 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
1aa50 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 ,.** the handler
1aa60 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 returns 0 which
1aa70 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 causes [sqlite3
1aa80 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 _step()] to retu
1aa90 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 rn.** [SQLITE_BU
1aaa0 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c SY]..**.** ^Call
1aab0 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ing this routine
1aac0 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e with an argumen
1aad0 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 t less than or e
1aae0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 qual to zero.**
1aaf0 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 turns off all bu
1ab00 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a sy handlers..**.
1ab10 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f ** ^(There can o
1ab20 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 nly be a single
1ab30 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 busy handler for
1ab40 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a a particular.**
1ab50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1ab60 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 ction] at any gi
1ab70 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 ven moment. If
1ab80 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e another busy han
1ab90 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 dler.** was defi
1aba0 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c ned (using [sql
1abb0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
1abc0 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 r()]) prior to c
1abd0 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 alling.** this r
1abe0 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 outine, that oth
1abf0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 er busy handler
1ac00 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a is cleared.)^.**
1ac10 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b .** See also: [
1ac20 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 PRAGMA busy_time
1ac30 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 out].*/.int sqli
1ac40 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
1ac50 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d (sqlite3*, int m
1ac60 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 s);../*.** CAPI3
1ac70 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 REF: Convenience
1ac80 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 Routines For Ru
1ac90 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a nning Queries.**
1aca0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
1acb0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 .**.** This is a
1acc0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
1acd0 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 e that is preser
1ace0 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ved for backward
1acf0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
1ad00 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 .** Use of this
1ad10 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 interface is not
1ad20 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a recommended..**
1ad30 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 .** Definition:
1ad40 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c A <b>result tabl
1ad50 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 e</b> is memory
1ad60 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 data structure c
1ad70 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a reated by the.**
1ad80 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
1ad90 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ble()] interface
1ada0 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c . A result tabl
1adb0 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a e records the.**
1adc0 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 complete query
1add0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 results from one
1ade0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 or more queries
1adf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c ..**.** The tabl
1ae00 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 e conceptually h
1ae10 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 as a number of r
1ae20 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e ows and columns.
1ae30 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e But.** these n
1ae40 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 umbers are not p
1ae50 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c art of the resul
1ae60 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 t table itself.
1ae70 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 These.** number
1ae80 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 s are obtained s
1ae90 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 eparately. Let
1aea0 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 N be the number
1aeb0 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d of rows.** and M
1aec0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
1aed0 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a f columns..**.**
1aee0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
1aef0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
1af00 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d ointers to zero-
1af10 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
1af20 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 strings..** The
1af30 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 re are (N+1)*M e
1af40 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 lements in the a
1af50 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 rray. The first
1af60 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e M pointers poin
1af70 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 t.** to zero-ter
1af80 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 minated strings
1af90 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 that contain th
1afa0 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 e names of the c
1afb0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 olumns..** The r
1afc0 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 emaining entries
1afd0 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 all point to qu
1afe0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 ery results. NU
1aff0 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 LL values result
1b000 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e .** in NULL poin
1b010 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 ters. All other
1b020 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 values are in t
1b030 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d heir UTF-8 zero-
1b040 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 terminated.** st
1b050 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 ring representat
1b060 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 ion as returned
1b070 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by [sqlite3_colu
1b080 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a mn_text()]..**.*
1b090 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
1b0a0 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f might consist o
1b0b0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 f one or more me
1b0c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
1b0d0 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 ..** It is not s
1b0e0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 afe to pass a re
1b0f0 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 sult table direc
1b100 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f tly to [sqlite3_
1b110 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 free()]..** A re
1b120 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c sult table shoul
1b130 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 d be deallocated
1b140 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
1b150 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a free_table()]..*
1b160 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 *.** ^(As an exa
1b170 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 mple of the resu
1b180 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c lt table format,
1b190 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 suppose a query
1b1a0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 result.** is as
1b1b0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
1b1c0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1b1d0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 >.** Name
1b1e0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a | Age.**
1b1f0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d --------
1b200 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a ---------------.
1b210 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 ** Alice
1b220 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 | 43.**
1b230 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 Bob
1b240 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 | 28.**
1b250 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 Cindy | 21
1b260 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1b270 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
1b280 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 ere are two colu
1b290 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 mn (M==2) and th
1b2a0 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e ree rows (N==3).
1b2b0 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 Thus the.** re
1b2c0 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 sult table has 8
1b2d0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f entries. Suppo
1b2e0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 se the result ta
1b2f0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a ble is stored.**
1b300 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d in an array nam
1b310 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 es azResult. Th
1b320 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 en azResult hold
1b330 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a s this content:.
1b340 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1b350 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 e><pre>.**
1b360 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 azResult[0
1b370 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 ] = "Name";.**
1b380 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1b390 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 91;1] = "Age";.*
1b3a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1b3b0 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 t[2] = "Alic
1b3c0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
1b3d0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 Result[3] =
1b3e0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 "43";.**
1b3f0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 azResult[4]
1b400 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 = "Bob";.**
1b410 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1b420 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 5] = "28";.**
1b430 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1b440 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 1;6] = "Cindy";.
1b450 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1b460 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 lt[7] = "21"
1b470 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
1b480 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a ckquote>)^.**.**
1b490 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 ^The sqlite3_ge
1b4a0 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 t_table() functi
1b4b0 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 on evaluates one
1b4c0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 or more.** semi
1b4d0 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 colon-separated
1b4e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 SQL statements i
1b4f0 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 n the zero-termi
1b500 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 nated UTF-8.** s
1b510 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 tring of its 2nd
1b520 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 parameter and r
1b530 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 eturns a result
1b540 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 table to the.**
1b550 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e pointer given in
1b560 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 its 3rd paramet
1b570 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 er..**.** After
1b580 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
1b590 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
1b5a0 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f h the result fro
1b5b0 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 m sqlite3_get_ta
1b5c0 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 ble(),.** it mus
1b5d0 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c t pass the resul
1b5e0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 t table pointer
1b5f0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f to sqlite3_free_
1b600 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 table() in order
1b610 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 to.** release t
1b620 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 he memory that w
1b630 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 as malloced. Be
1b640 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 cause of the way
1b650 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
1b660 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 _malloc()] happe
1b670 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 ns within sqlite
1b680 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 3_get_table(), t
1b690 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 he calling.** fu
1b6a0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 nction must not
1b6b0 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c try to call [sql
1b6c0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 ite3_free()] dir
1b6d0 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 ectly. Only.**
1b6e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 [sqlite3_free_ta
1b6f0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 ble()] is able t
1b700 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 o release the me
1b710 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e mory properly an
1b720 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 d safely..**.**
1b730 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
1b740 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 table() interfac
1b750 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 e is implemented
1b760 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 as a wrapper ar
1b770 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ound.** [sqlite3
1b780 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 _exec()]. The s
1b790 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
1b7a0 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 () routine does
1b7b0 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a not have access.
1b7c0 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e ** to any intern
1b7d0 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 al data structur
1b7e0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 es of SQLite. I
1b7f0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 t uses only the
1b800 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 public.** interf
1b810 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 ace defined here
1b820 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 . As a conseque
1b830 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 nce, errors that
1b840 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a occur in the.**
1b850 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f wrapper layer o
1b860 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e utside of the in
1b870 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f ternal [sqlite3_
1b880 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 exec()] call are
1b890 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 not.** reflecte
1b8a0 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 d in subsequent
1b8b0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
1b8c0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 3_errcode()] or.
1b8d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ** [sqlite3_errm
1b8e0 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 sg()]..*/.int sq
1b8f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1b900 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
1b910 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f /* An o
1b920 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a pen database */.
1b930 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
1b940 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 ql, /* SQL t
1b950 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a o be evaluated *
1b960 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 /. char ***pazR
1b970 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 esult, /* Res
1b980 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 ults of the quer
1b990 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f y */. int *pnRo
1b9a0 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 w, /*
1b9b0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 Number of result
1b9c0 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 rows written he
1b9d0 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 re */. int *pnC
1b9e0 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a olumn, /*
1b9f0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c Number of resul
1ba00 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 t columns writte
1ba10 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 n here */. char
1ba20 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 **pzErrmsg
1ba30 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 /* Error msg w
1ba40 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 ritten here */.)
1ba50 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 ;.void sqlite3_f
1ba60 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a ree_table(char *
1ba70 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a *result);../*.**
1ba80 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 CAPI3REF: Forma
1ba90 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e tted String Prin
1baa0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ting Functions.*
1bab0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1bac0 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 nes are work-ali
1bad0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e kes of the "prin
1bae0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 tf()" family of
1baf0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f functions.** fro
1bb00 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 m the standard C
1bb10 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 library..** The
1bb20 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 se routines unde
1bb30 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 rstand most of t
1bb40 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f he common K&R fo
1bb50 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 rmatting options
1bb60 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 ,.** plus some a
1bb70 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 dditional non-st
1bb80 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 andard formats,
1bb90 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a detailed below..
1bba0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d ** Note that som
1bbb0 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 e of the more ob
1bbc0 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 scure formatting
1bbd0 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 options from re
1bbe0 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 cent.** C-librar
1bbf0 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 y standards are
1bc00 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 omitted from thi
1bc10 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
1bc20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
1bc30 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 ite3_mprintf() a
1bc40 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 nd sqlite3_vmpri
1bc50 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 ntf() routines w
1bc60 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 rite their.** re
1bc70 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 sults into memor
1bc80 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
1bc90 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1bca0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e )]..** The strin
1bcb0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 gs returned by t
1bcc0 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 hese two routine
1bcd0 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 s should be.** r
1bce0 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 eleased by [sqli
1bcf0 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 te3_free()]. ^B
1bd00 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 oth routines ret
1bd10 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f urn a.** NULL po
1bd20 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 inter if [sqlite
1bd30 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 3_malloc()] is u
1bd40 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
1bd50 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f e enough.** memo
1bd60 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 ry to hold the r
1bd70 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e esulting string.
1bd80 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c .**.** ^(The sql
1bd90 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 ite3_snprintf()
1bda0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c routine is simil
1bdb0 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 ar to "snprintf(
1bdc0 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 )" from.** the s
1bdd0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
1bde0 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 y. The result i
1bdf0 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 s written into t
1be00 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 he.** buffer sup
1be10 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 plied as the sec
1be20 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 ond parameter wh
1be30 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 ose size is give
1be40 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 n by.** the firs
1be50 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 t parameter. Not
1be60 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 e that the order
1be70 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 of the.** first
1be80 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 two parameters
1be90 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d is reversed from
1bea0 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 snprintf().)^
1beb0 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 This is an.** hi
1bec0 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e storical acciden
1bed0 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 t that cannot be
1bee0 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 fixed without b
1bef0 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 reaking.** backw
1bf00 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
1bf10 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f ty. ^(Note also
1bf20 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e that sqlite3_sn
1bf30 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 printf().** retu
1bf40 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1bf50 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 its buffer inst
1bf60 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 ead of the numbe
1bf70 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 r of.** characte
1bf80 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 rs actually writ
1bf90 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 ten into the buf
1bfa0 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 fer.)^ We admit
1bfb0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d that.** the num
1bfc0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
1bfd0 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 s written would
1bfe0 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c be a more useful
1bff0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 return.** value
1c000 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 but we cannot c
1c010 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d hange the implem
1c020 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 entation of sqli
1c030 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
1c040 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 * now without br
1c050 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 eaking compatibi
1c060 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 lity..**.** ^As
1c070 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 long as the buff
1c080 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 er size is great
1c090 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 er than zero, sq
1c0a0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
1c0b0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 .** guarantees t
1c0c0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 hat the buffer i
1c0d0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 s always zero-te
1c0e0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 rminated. ^The
1c0f0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 first.** paramet
1c100 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f er "n" is the to
1c110 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 tal size of the
1c120 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e buffer, includin
1c130 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 g space for.** t
1c140 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 he zero terminat
1c150 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 or. So the long
1c160 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 est string that
1c170 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c can be completel
1c180 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c y.** written wil
1c190 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 l be n-1 charact
1c1a0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ers..**.** ^The
1c1b0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 sqlite3_vsnprint
1c1c0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 f() routine is a
1c1d0 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e varargs version
1c1e0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 of sqlite3_snpr
1c1f0 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 intf()..**.** Th
1c200 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c ese routines all
1c210 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 implement some
1c220 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 additional forma
1c230 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 tting.** options
1c240 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c that are useful
1c250 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e for constructin
1c260 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 g SQL statements
1c270 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 ..** All of the
1c280 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 usual printf() f
1c290 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
1c2a0 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 s apply. In add
1c2b0 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 ition, there.**
1c2c0 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 is are "%q", "%Q
1c2d0 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 ", "%w" and "%z"
1c2e0 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 options..**.**
1c2f0 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 ^(The %q option
1c300 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e works like %s in
1c310 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 that it substit
1c320 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 utes a nul-termi
1c330 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 nated.** string
1c340 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e from the argumen
1c350 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 t list. But %q
1c360 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 also doubles eve
1c370 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 ry '\'' characte
1c380 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 r..** %q is desi
1c390 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 gned for use ins
1c3a0 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 ide a string lit
1c3b0 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 eral.)^ By doub
1c3c0 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a ling each '\''.*
1c3d0 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 * character it e
1c3e0 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 scapes that char
1c3f0 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 acter and allows
1c400 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 it to be insert
1c410 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 ed into.** the s
1c420 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 tring..**.** For
1c430 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 example, assume
1c440 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 the string vari
1c450 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 able zText conta
1c460 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c ins text as foll
1c470 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
1c480 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
1c490 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 char *zText = "
1c4a0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 It's a happy day
1c4b0 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 !";.** </pre></b
1c4c0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1c4d0 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 One can use thi
1c4e0 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c s text in an SQL
1c4f0 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f statement as fo
1c500 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c llows:.**.** <bl
1c510 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1c520 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 * char *zSQL =
1c530 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1c540 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 "INSERT INTO tab
1c550 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 le VALUES('%q')"
1c560 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 , zText);.** sq
1c570 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a lite3_exec(db, z
1c580 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a SQL, 0, 0, 0);.*
1c590 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * sqlite3_free(
1c5a0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e zSQL);.** </pre>
1c5b0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1c5c0 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 .** Because the
1c5d0 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 %q format string
1c5e0 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c is used, the '\
1c5f0 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 '' character in
1c600 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 zText.** is esca
1c610 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 ped and the SQL
1c620 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 generated is as
1c630 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
1c640 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1c650 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f .** INSERT INTO
1c660 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 table1 VALUES('
1c670 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 It''s a happy da
1c680 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f y!').** </pre></
1c690 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
1c6a0 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 * This is correc
1c6b0 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 t. Had we used
1c6c0 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 %s instead of %q
1c6d0 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 , the generated
1c6e0 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 SQL.** would hav
1c6f0 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 e looked like th
1c700 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b is:.**.** <block
1c710 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1c720 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
1c730 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 e1 VALUES('It's
1c740 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a a happy day!');.
1c750 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1c760 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 quote>.**.** Thi
1c770 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 s second example
1c780 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 is an SQL synta
1c790 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 x error. As a g
1c7a0 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 eneral rule you
1c7b0 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 should.** always
1c7c0 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 use %q instead
1c7d0 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 of %s when inser
1c7e0 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 ting text into a
1c7f0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e string literal.
1c800 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 .**.** ^(The %Q
1c810 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
1c820 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 e %q except it a
1c830 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 lso adds single
1c840 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a quotes around.**
1c850 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 the outside of
1c860 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 the total string
1c870 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c . Additionally,
1c880 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
1c890 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 r in the.** argu
1c8a0 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e ment list is a N
1c8b0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 ULL pointer, %Q
1c8c0 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 substitutes the
1c8d0 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 text "NULL" (wit
1c8e0 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 hout.** single q
1c8f0 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 uotes).)^ So, f
1c900 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 or example, one
1c910 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a could say:.**.**
1c920 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1c930 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 e>.** char *zSQ
1c940 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 L = sqlite3_mpri
1c950 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f ntf("INSERT INTO
1c960 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 table VALUES(%Q
1c970 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 )", zText);.**
1c980 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c sqlite3_exec(db,
1c990 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b zSQL, 0, 0, 0);
1c9a0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 .** sqlite3_fre
1c9b0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 e(zSQL);.** </pr
1c9c0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1c9d0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 **.** The code a
1c9e0 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 bove will render
1c9f0 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 a correct SQL s
1ca00 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 tatement in the
1ca10 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 zSQL.** variable
1ca20 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 even if the zTe
1ca30 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 xt variable is a
1ca40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
1ca50 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 *.** ^(The "%w"
1ca60 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f formatting optio
1ca70 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 n is like "%q" e
1ca80 78 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78 xcept that it ex
1ca90 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 pects to.** be c
1caa0 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 ontained within
1cab0 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e double-quotes in
1cac0 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 stead of single
1cad0 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a quotes, and it.*
1cae0 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f * escapes the do
1caf0 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 uble-quote chara
1cb00 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 cter instead of
1cb10 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 the single-quote
1cb20 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e .** character.)^
1cb30 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 The "%w" forma
1cb40 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 tting option is
1cb50 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 intended for saf
1cb60 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a ely inserting.**
1cb70 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d table and colum
1cb80 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 n names into a c
1cb90 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 onstructed SQL s
1cba0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 tatement..**.**
1cbb0 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 ^(The "%z" forma
1cbc0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 tting option wor
1cbd0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 ks like "%s" but
1cbe0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 with the.** add
1cbf0 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 ition that after
1cc00 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 the string has
1cc10 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f been read and co
1cc20 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 pied into.** the
1cc30 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 result, [sqlite
1cc40 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 3_free()] is cal
1cc50 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 led on the input
1cc60 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 string.)^.*/.ch
1cc70 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 ar *sqlite3_mpri
1cc80 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c ntf(const char*,
1cc90 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 ...);.char *sqli
1cca0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e te3_vmprintf(con
1ccb0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 st char*, va_lis
1ccc0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 t);.char *sqlite
1ccd0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 3_snprintf(int,c
1cce0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
1ccf0 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 , ...);.char *sq
1cd00 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 lite3_vsnprintf(
1cd10 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 int,char*,const
1cd20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b char*, va_list);
1cd30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1cd40 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
1cd50 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a ion Subsystem.**
1cd60 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
1cd70 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 ore uses these t
1cd80 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hree routines fo
1cd90 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e r all of its own
1cda0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d .** internal mem
1cdb0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
1cdc0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 eeds. "Core" in
1cdd0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e the previous sen
1cde0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f tence.** does no
1cdf0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 t include operat
1ce00 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
1ce10 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e fic VFS implemen
1ce20 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 tation. The.**
1ce30 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 Windows VFS uses
1ce40 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 native malloc()
1ce50 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 and free() for
1ce60 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e some operations.
1ce70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1ce80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 te3_malloc() rou
1ce90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
1cea0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 ointer to a bloc
1ceb0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 k.** of memory a
1cec0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
1ced0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 in length, where
1cee0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 N is the parame
1cef0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ter..** ^If sqli
1cf00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 te3_malloc() is
1cf10 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e unable to obtain
1cf20 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 sufficient free
1cf30 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 .** memory, it r
1cf40 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
1cf50 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 inter. ^If the
1cf60 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a parameter N to.*
1cf70 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
1cf80 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 () is zero or ne
1cf90 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 gative then sqli
1cfa0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 te3_malloc() ret
1cfb0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 urns.** a NULL p
1cfc0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ointer..**.** ^T
1cfd0 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f he sqlite3_mallo
1cfe0 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 c64(N) routine w
1cff0 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a orks just like.*
1d000 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
1d010 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 (N) except that
1d020 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 N is an unsigned
1d030 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
1d040 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 instead.** of a
1d050 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e signed 32-bit in
1d060 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 teger..**.** ^Ca
1d070 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 lling sqlite3_fr
1d080 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e ee() with a poin
1d090 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 ter previously r
1d0a0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 eturned.** by sq
1d0b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f lite3_malloc() o
1d0c0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
1d0d0 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 c() releases tha
1d0e0 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 t memory so.** t
1d0f0 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 hat it might be
1d100 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 reused. ^The sq
1d110 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 lite3_free() rou
1d120 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d tine is.** a no-
1d130 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 op if is called
1d140 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
1d150 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 ter. Passing a
1d160 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
1d170 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 to sqlite3_free(
1d180 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 ) is harmless.
1d190 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 After being free
1d1a0 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f d, memory.** sho
1d1b0 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 uld neither be r
1d1c0 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e ead nor written.
1d1d0 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 Even reading p
1d1e0 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a reviously freed.
1d1f0 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 ** memory might
1d200 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d result in a segm
1d210 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f entation fault o
1d220 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 r other severe e
1d230 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 rror..** Memory
1d240 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 corruption, a se
1d250 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 gmentation fault
1d260 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 , or other sever
1d270 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 e error.** might
1d280 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 result if sqlit
1d290 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c e3_free() is cal
1d2a0 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e led with a non-N
1d2b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ULL pointer that
1d2c0 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 .** was not obta
1d2d0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
1d2e0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 3_malloc() or sq
1d2f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e lite3_realloc().
1d300 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1d310 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1d320 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
1d330 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a pts to resize a.
1d340 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 ** prior memory
1d350 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 allocation X to
1d360 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 be at least N by
1d370 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 tes..** ^If the
1d380 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 X parameter to s
1d390 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
1d3a0 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c ,N).** is a NULL
1d3b0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 pointer then it
1d3c0 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 s behavior is id
1d3d0 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 entical to calli
1d3e0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 ng.** sqlite3_ma
1d3f0 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 lloc(N)..** ^If
1d400 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 the N parameter
1d410 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
1d420 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 oc(X,N) is zero
1d430 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 or.** negative t
1d440 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
1d450 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 is exactly the
1d460 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a same as calling.
1d470 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 ** sqlite3_free(
1d480 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f X)..** ^sqlite3_
1d490 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 realloc(X,N) ret
1d4a0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
1d4b0 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 o a memory alloc
1d4c0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c ation.** of at l
1d4d0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 east N bytes in
1d4e0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 size or NULL if
1d4f0 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d insufficient mem
1d500 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 ory is available
1d510 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 ..** ^If M is th
1d520 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 e size of the pr
1d530 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 ior allocation,
1d540 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 then min(N,M) by
1d550 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 tes.** of the pr
1d560 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 ior allocation a
1d570 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 re copied into t
1d580 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
1d590 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a buffer returned.
1d5a0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 ** by sqlite3_re
1d5b0 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 alloc(X,N) and t
1d5c0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
1d5d0 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a ion is freed..**
1d5e0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 ^If sqlite3_rea
1d5f0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e lloc(X,N) return
1d600 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 s NULL and N is
1d610 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 positive, then t
1d620 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f he.** prior allo
1d630 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 cation is not fr
1d640 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 eed..**.** ^The
1d650 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 sqlite3_realloc6
1d660 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 4(X,N) interface
1d670 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 s works the same
1d680 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 as.** sqlite3_r
1d690 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 ealloc(X,N) exce
1d6a0 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 pt that N is a 6
1d6b0 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 4-bit unsigned i
1d6c0 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a nteger instead.*
1d6d0 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 * of a 32-bit si
1d6e0 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a gned integer..**
1d6f0 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d .** ^If X is a m
1d700 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1d710 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 previously obta
1d720 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
1d730 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 3_malloc(),.** s
1d740 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 qlite3_malloc64(
1d750 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c ), sqlite3_reall
1d760 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 oc(), or sqlite3
1d770 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 _realloc64(), th
1d780 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 en.** sqlite3_ms
1d790 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 ize(X) returns t
1d7a0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 he size of that
1d7b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1d7c0 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e n in bytes..** ^
1d7d0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e The value return
1d7e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 ed by sqlite3_ms
1d7f0 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 ize(X) might be
1d800 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 larger than the
1d810 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 number.** of byt
1d820 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 es requested whe
1d830 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 n X was allocate
1d840 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e d. ^If X is a N
1d850 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
1d860 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a .** sqlite3_msiz
1d870 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 e(X) returns zer
1d880 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 o. If X points
1d890 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 to something tha
1d8a0 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 t is not.** the
1d8b0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d beginning of mem
1d8c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 ory allocation,
1d8d0 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 or if it points
1d8e0 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a to a formerly.**
1d8f0 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c valid memory al
1d900 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 location that ha
1d910 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 s now been freed
1d920 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
1d930 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 ior.** of sqlite
1d940 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 3_msize(X) is un
1d950 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 defined and poss
1d960 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a ibly harmful..**
1d970 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 .** ^The memory
1d980 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
1d990 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 te3_malloc(), sq
1d9a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c lite3_realloc(),
1d9b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c .** sqlite3_mall
1d9c0 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 oc64(), and sqli
1d9d0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a te3_realloc64().
1d9e0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 ** is always ali
1d9f0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 gned to at least
1da00 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 an 8 byte bound
1da10 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 ary, or to a.**
1da20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 4 byte boundary
1da30 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 if the [SQLITE_4
1da40 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 _BYTE_ALIGNED_MA
1da50 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 LLOC] compile-ti
1da60 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 me.** option is
1da70 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 used..**.** In S
1da80 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
1da90 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 5.0 and 3.5.1, i
1daa0 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 t was possible t
1dab0 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 o define.** the
1dac0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f SQLITE_OMIT_MEMO
1dad0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 RY_ALLOCATION wh
1dae0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 ich would cause
1daf0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 the built-in.**
1db00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
1db10 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
1db20 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 to be omitted.
1db30 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 That capability
1db40 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 .** is no longer
1db50 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 provided. Only
1db60 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
1db70 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 allocators can
1db80 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 be used..**.** P
1db90 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 rior to SQLite v
1dba0 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 ersion 3.7.10, t
1dbb0 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e he Windows OS in
1dbc0 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 terface layer ca
1dbd0 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 lled.** the syst
1dbe0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 em malloc() and
1dbf0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 free() directly
1dc00 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a when converting.
1dc10 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 ** filenames bet
1dc20 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 ween the UTF-8 e
1dc30 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 ncoding used by
1dc40 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 SQLite.** and wh
1dc50 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 atever filename
1dc60 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 encoding is used
1dc70 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c by the particul
1dc80 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e ar Windows.** in
1dc90 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d stallation. Mem
1dca0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
1dcb0 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 rrors were detec
1dcc0 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 ted, but.** they
1dcd0 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 were reported b
1dce0 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 ack as [SQLITE_C
1dcf0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b ANTOPEN] or.** [
1dd00 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 SQLITE_IOERR] ra
1dd10 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
1dd20 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 E_NOMEM]..**.**
1dd30 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 The pointer argu
1dd40 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 ments to [sqlite
1dd50 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 3_free()] and [s
1dd60 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1dd70 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 ].** must be eit
1dd80 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 her NULL or else
1dd90 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e pointers obtain
1dda0 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a ed from a prior.
1ddb0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ** invocation of
1ddc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1ddd0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1dde0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 realloc()] that
1ddf0 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 have.** not yet
1de00 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a been released..*
1de10 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
1de20 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 tion must not re
1de30 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 ad or write any
1de40 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f part of.** a blo
1de50 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 ck of memory aft
1de60 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 er it has been r
1de70 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a eleased using.**
1de80 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1de90 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
1dea0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 alloc()]..*/.voi
1deb0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f d *sqlite3_mallo
1dec0 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 c(int);.void *sq
1ded0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 lite3_malloc64(s
1dee0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a qlite3_uint64);.
1def0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 void *sqlite3_re
1df00 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 alloc(void*, int
1df10 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 );.void *sqlite3
1df20 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a _realloc64(void*
1df30 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 , sqlite3_uint64
1df40 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
1df50 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c free(void*);.sql
1df60 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 ite3_uint64 sqli
1df70 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 te3_msize(void*)
1df80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1df90 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
1dfa0 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a tor Statistics.*
1dfb0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 *.** SQLite prov
1dfc0 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 ides these two i
1dfd0 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 nterfaces for re
1dfe0 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 porting on the s
1dff0 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 tatus.** of the
1e000 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1e010 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 )], [sqlite3_fre
1e020 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 e()], and [sqlit
1e030 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a e3_realloc()].**
1e040 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 routines, which
1e050 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d form the built-
1e060 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
1e070 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a tion subsystem..
1e080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 **.** ^The [sqli
1e090 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
1e0a0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 )] routine retur
1e0b0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
1e0c0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d bytes.** of mem
1e0d0 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 ory currently ou
1e0e0 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f tstanding (mallo
1e0f0 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 ced but not free
1e100 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c d)..** ^The [sql
1e110 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
1e120 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 water()] routine
1e130 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 returns the max
1e140 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 imum.** value of
1e150 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1e160 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 _used()] since t
1e170 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
1e180 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 rk.** was last r
1e190 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 eset. ^The valu
1e1a0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b es returned by [
1e1b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
1e1c0 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 sed()] and.** [s
1e1d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
1e1e0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 ghwater()] inclu
1e1f0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a de any overhead.
1e200 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 ** added by SQLi
1e210 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d te in its implem
1e220 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c entation of [sql
1e230 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a ite3_malloc()],.
1e240 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 ** but not overh
1e250 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 ead added by the
1e260 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 any underlying
1e270 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a system library.*
1e280 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 * routines that
1e290 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1e2a0 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a )] may call..**.
1e2b0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 ** ^The memory h
1e2c0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 igh-water mark i
1e2d0 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 s reset to the c
1e2e0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a urrent value of.
1e2f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ** [sqlite3_memo
1e300 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e ry_used()] if an
1e310 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 d only if the pa
1e320 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 rameter to.** [s
1e330 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
1e340 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 ghwater()] is tr
1e350 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 ue. ^The value
1e360 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b returned.** by [
1e370 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
1e380 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 ighwater(1)] is
1e390 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d the high-water m
1e3a0 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 ark.** prior to
1e3b0 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 the reset..*/.sq
1e3c0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
1e3d0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
1e3e0 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 void);.sqlite3_i
1e3f0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d nt64 sqlite3_mem
1e400 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e ory_highwater(in
1e410 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f t resetFlag);../
1e420 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 *.** CAPI3REF: P
1e430 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d seudo-Random Num
1e440 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a ber Generator.**
1e450 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 .** SQLite conta
1e460 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 ins a high-quali
1e470 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d ty pseudo-random
1e480 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f number generato
1e490 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f r (PRNG) used to
1e4a0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f .** select rando
1e4b0 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 m [ROWID | ROWID
1e4c0 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e s] when insertin
1e4d0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e g new records in
1e4e0 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a to a table that.
1e4f0 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 ** already uses
1e500 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 the largest poss
1e510 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 ible [ROWID]. T
1e520 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 he PRNG is also
1e530 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 used for.** the
1e540 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 build-in random(
1e550 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 ) and randomblob
1e560 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 () SQL functions
1e570 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 . This interfac
1e580 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c e allows.** appl
1e590 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 ications to acce
1e5a0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 ss the same PRNG
1e5b0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f for other purpo
1e5c0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 ses..**.** ^A ca
1e5d0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 ll to this routi
1e5e0 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 ne stores N byte
1e5f0 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 s of randomness
1e600 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a into buffer P..*
1e610 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 * ^The P paramet
1e620 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c er can be a NULL
1e630 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
1e640 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ^If this routine
1e650 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 has not been pr
1e660 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 eviously called
1e670 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f or if the previo
1e680 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e us.** call had N
1e690 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f less than one o
1e6a0 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
1e6b0 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 for P, then the
1e6c0 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 PRNG is.** seed
1e6d0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e ed using randomn
1e6e0 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ess obtained fro
1e6f0 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 m the xRandomnes
1e700 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 s method of.** t
1e710 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
1e720 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
1e730 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 .** ^If the prev
1e740 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 ious call to thi
1e750 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e s routine had an
1e760 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 N of 1 or more
1e770 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c and a.** non-NUL
1e780 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 L P then the pse
1e790 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 udo-randomness i
1e7a0 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 s generated.** i
1e7b0 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 nternally and wi
1e7c0 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 thout recourse t
1e7d0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
1e7e0 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a fs] xRandomness.
1e7f0 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f ** method..*/.vo
1e800 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f id sqlite3_rando
1e810 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 mness(int N, voi
1e820 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 d *P);../*.** CA
1e830 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d PI3REF: Compile-
1e840 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 Time Authorizati
1e850 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 on Callbacks.**
1e860 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
1e870 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
1e880 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e ine registers an
1e890 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1e8a0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 back with a part
1e8b0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
1e8c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c ase connection],
1e8d0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 supplied in the
1e8e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
1e8f0 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 .** ^The authori
1e900 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
1e910 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 invoked as SQL s
1e920 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 tatements are be
1e930 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 ing compiled.**
1e940 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 by [sqlite3_prep
1e950 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 are()] or its va
1e960 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f riants [sqlite3_
1e970 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a prepare_v2()],.*
1e980 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
1e990 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c re16()] and [sql
1e9a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1e9b0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 2()]. ^At vario
1e9c0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 us.** points dur
1e9d0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 ing the compilat
1e9e0 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 ion process, as
1e9f0 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 logic is being c
1ea00 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 reated.** to per
1ea10 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 form various act
1ea20 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 ions, the author
1ea30 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
1ea40 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 invoked to.** s
1ea50 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 ee if those acti
1ea60 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e ons are allowed.
1ea70 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 ^The authorize
1ea80 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c r callback shoul
1ea90 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c d.** return [SQL
1eaa0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 ITE_OK] to allow
1eab0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 the action, [SQ
1eac0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 LITE_IGNORE] to
1ead0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 disallow the.**
1eae0 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 specific action
1eaf0 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 but allow the SQ
1eb00 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 L statement to c
1eb10 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a ontinue to be.**
1eb20 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 compiled, or [S
1eb30 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 QLITE_DENY] to c
1eb40 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 ause the entire
1eb50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f SQL statement to
1eb60 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 be.** rejected
1eb70 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 with an error.
1eb80 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a ^If the authoriz
1eb90 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 er callback retu
1eba0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 rns.** any value
1ebb0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
1ebc0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 ITE_IGNORE], [SQ
1ebd0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 LITE_OK], or [SQ
1ebe0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 LITE_DENY].** th
1ebf0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f en the [sqlite3_
1ec00 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
1ec10 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c equivalent call
1ec20 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a that triggered.
1ec30 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ** the authorize
1ec40 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 r will fail with
1ec50 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
1ec60 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 e..**.** When th
1ec70 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
1ec80 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ns [SQLITE_OK],
1ec90 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f that means the o
1eca0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 peration.** requ
1ecb0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 ested is ok. ^W
1ecc0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
1ecd0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
1ece0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b _DENY], the.** [
1ecf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1ed00 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c v2()] or equival
1ed10 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ent call that tr
1ed20 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 iggered the.** a
1ed30 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 uthorizer will f
1ed40 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f ail with an erro
1ed50 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 r message explai
1ed60 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 ning that.** acc
1ed70 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a ess is denied. .
1ed80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
1ed90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1eda0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1edb0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 lback is a copy
1edc0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 of the third.**
1edd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
1ede0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
1edf0 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 horizer() interf
1ee00 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 ace. ^The second
1ee10 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f parameter.** to
1ee20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
1ee30 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c an integer [SQL
1ee40 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f ITE_COPY | actio
1ee50 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 n code] that spe
1ee60 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 cifies.** the pa
1ee70 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 rticular action
1ee80 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
1ee90 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 . ^The third thr
1eea0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d ough sixth param
1eeb0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 eters.** to the
1eec0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 callback are zer
1eed0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
1eee0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 ings that contai
1eef0 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 n additional.**
1ef00 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 details about th
1ef10 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 e action to be a
1ef20 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a uthorized..**.**
1ef30 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 ^If the action
1ef40 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f code is [SQLITE_
1ef50 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 READ].** and the
1ef60 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
1ef70 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 s [SQLITE_IGNORE
1ef80 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 ] then the.** [p
1ef90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1efa0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 t] statement is
1efb0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 constructed to s
1efc0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e ubstitute.** a N
1efd0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 ULL value in pla
1efe0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 ce of the table
1eff0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c column that woul
1f000 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 d have.** been r
1f010 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f ead if [SQLITE_O
1f020 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 K] had been retu
1f030 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 rned. The [SQLI
1f040 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 TE_IGNORE].** re
1f050 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 turn can be used
1f060 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 to deny an untr
1f070 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 usted user acces
1f080 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a s to individual.
1f090 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 ** columns of a
1f0a0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 table..** ^If th
1f0b0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 e action code is
1f0c0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d [SQLITE_DELETE]
1f0d0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 and the callbac
1f0e0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 k returns.** [SQ
1f0f0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 LITE_IGNORE] the
1f100 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f n the [DELETE] o
1f110 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 peration proceed
1f120 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 s but the.** [tr
1f130 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 uncate optimizat
1f140 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 ion] is disabled
1f150 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 and all rows ar
1f160 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 e deleted indivi
1f170 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e dually..**.** An
1f180 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 authorizer is u
1f190 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 sed when [sqlite
1f1a0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
1f1b0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 aring].** SQL st
1f1c0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e atements from an
1f1d0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 untrusted sourc
1f1e0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 e, to ensure tha
1f1f0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d t the SQL statem
1f200 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 ents.** do not t
1f210 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 ry to access dat
1f220 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 a they are not a
1f230 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f llowed to see, o
1f240 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e r that they do n
1f250 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 ot.** try to exe
1f260 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 cute malicious s
1f270 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 tatements that d
1f280 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 amage the databa
1f290 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d se. For.** exam
1f2a0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 ple, an applicat
1f2b0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 ion may allow a
1f2c0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 user to enter ar
1f2d0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 bitrary.** SQL q
1f2e0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 ueries for evalu
1f2f0 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 ation by a datab
1f300 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 ase. But the ap
1f310 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a plication does.*
1f320 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 * not want the u
1f330 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 ser to be able t
1f340 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 o make arbitrary
1f350 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a changes to the.
1f360 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e ** database. An
1f370 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c authorizer coul
1f380 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e d then be put in
1f390 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 place while the
1f3a0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 .** user-entered
1f3b0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 SQL is being [s
1f3c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c qlite3_prepare |
1f3d0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a prepared] that.
1f3e0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 ** disallows eve
1f3f0 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b rything except [
1f400 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
1f410 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 ts..**.** Applic
1f420 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 ations that need
1f430 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 to process SQL
1f440 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 from untrusted s
1f450 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 ources.** might
1f460 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f also consider lo
1f470 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 wering resource
1f480 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 limits using [sq
1f490 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a lite3_limit()].*
1f4a0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 * and limiting d
1f4b0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 atabase size usi
1f4c0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 ng the [max_page
1f4d0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
1f4e0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 .** in addition
1f4f0 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 to using an auth
1f500 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 orizer..**.** ^(
1f510 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 Only a single au
1f520 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 thorizer can be
1f530 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 in place on a da
1f540 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1f550 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 n.** at a time.
1f560 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 Each call to sq
1f570 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
1f580 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 izer overrides t
1f590 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 he.** previous c
1f5a0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 all.)^ ^Disable
1f5b0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1f5c0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 by installing a
1f5d0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a NULL callback..*
1f5e0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
1f5f0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 is disabled by
1f600 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 default..**.** T
1f610 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
1f620 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 llback must not
1f630 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 do anything that
1f640 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 will modify.**
1f650 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1f660 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
1f670 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 oked the authori
1f680 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a zer callback..**
1f690 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
1f6a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1f6b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
1f6c0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
1f6d0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
1f6e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
1f6f0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
1f700 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
1f710 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
1f720 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c **.** ^When [sql
1f730 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1f740 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 )] is used to pr
1f750 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e epare a statemen
1f760 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d t, the.** statem
1f770 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d ent might be re-
1f780 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 prepared during
1f790 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1f7a0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 due to a .** sc
1f7b0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 hema change. He
1f7c0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 nce, the applica
1f7d0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 tion should ensu
1f7e0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 re that the.** c
1f7f0 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 orrect authorize
1f800 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 r callback remai
1f810 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 ns in place duri
1f820 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ng the [sqlite3_
1f830 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e step()]..**.** ^
1f840 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 Note that the au
1f850 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1f860 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c k is invoked onl
1f870 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c y during.** [sql
1f880 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
1f890 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e or its variants.
1f8a0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 Authorization
1f8b0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 is not.** perfor
1f8c0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 med during state
1f8d0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 ment evaluation
1f8e0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 in [sqlite3_step
1f8f0 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 ()], unless.** a
1f900 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 s stated in the
1f910 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 previous paragra
1f920 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 ph, sqlite3_step
1f930 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 () invokes.** sq
1f940 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1f950 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 () to reprepare
1f960 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 a statement afte
1f970 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 r a schema chang
1f980 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
1f990 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
1f9a0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 (. sqlite3*,.
1f9b0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 int (*xAuth)(voi
1f9c0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
1f9d0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
1f9e0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
1f9f0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 char*),. void
1fa00 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f *pUserData.);../
1fa10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
1fa20 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e uthorizer Return
1fa30 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Codes.**.** The
1fa40 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
1fa50 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
1fa60 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 rizer callback f
1fa70 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a unction] must.**
1fa80 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b return either [
1fa90 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e SQLITE_OK] or on
1faa0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 e of these two c
1fab0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 onstants in orde
1fac0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 r.** to signal S
1fad0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 QLite whether or
1fae0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 not the action
1faf0 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 is permitted. S
1fb00 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ee the.** [sqlit
1fb10 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1fb20 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 r | authorizer d
1fb30 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
1fb40 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
1fb50 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
1fb60 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c ** Note that SQL
1fb70 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c ITE_IGNORE is al
1fb80 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f so used as a [co
1fb90 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f nflict resolutio
1fba0 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 n mode].** retur
1fbb0 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 ned from the [sq
1fbc0 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f lite3_vtab_on_co
1fbd0 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 nflict()] interf
1fbe0 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ace..*/.#define
1fbf0 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 SQLITE_DENY 1
1fc00 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 /* Abort the S
1fc10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 QL statement wit
1fc20 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 h an error */.#d
1fc30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e efine SQLITE_IGN
1fc40 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 ORE 2 /* Don't
1fc50 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 allow access, b
1fc60 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 ut don't generat
1fc70 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f e an error */../
1fc80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
1fc90 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e uthorizer Action
1fca0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Codes.**.** The
1fcb0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
1fcc0 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 thorizer()] inte
1fcd0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
1fce0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
1fcf0 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 ion.** that is i
1fd00 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 nvoked to author
1fd10 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 ize certain SQL
1fd20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e statement action
1fd30 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e s. The.** secon
1fd40 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
1fd50 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
1fd60 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 n integer code t
1fd70 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a hat specifies.**
1fd80 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 what action is
1fd90 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 being authorized
1fda0 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 . These are the
1fdb0 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 integer action
1fdc0 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 codes that.** th
1fdd0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1fde0 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 lback may be pas
1fdf0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 sed..**.** These
1fe00 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c action code val
1fe10 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 ues signify what
1fe20 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 kind of operati
1fe30 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 on is to be.** a
1fe40 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 uthorized. The
1fe50 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 3rd and 4th para
1fe60 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 meters to the au
1fe70 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 thorization.** c
1fe80 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1fe90 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 will be paramet
1fea0 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 ers or NULL depe
1feb0 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f nding on which o
1fec0 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 f these.** codes
1fed0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 is used as the
1fee0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1fef0 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 . ^(The 5th par
1ff00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ameter to the.**
1ff10 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1ff20 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 back is the name
1ff30 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
1ff40 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 ("main", "temp"
1ff50 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 ,.** etc.) if ap
1ff60 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 plicable.)^ ^Th
1ff70 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 6th parameter
1ff80 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 to the authorize
1ff90 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 r callback.** is
1ffa0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
1ffb0 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 inner-most trig
1ffc0 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 ger or view that
1ffd0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
1ffe0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 for.** the acces
1fff0 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c s attempt or NUL
20000 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 L if this access
20010 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 attempt is dire
20020 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 ctly from.** top
20030 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e -level SQL code.
20040 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .*/./***********
20050 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
20060 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
20070 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 3rd ***********
20080 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a * 4th **********
20090 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
200a0 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 E_CREATE_INDEX
200b0 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 1 /* I
200c0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
200d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
200e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
200f0 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 _CREATE_TABLE
20100 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 2 /* Ta
20110 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
20120 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
20130 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20140 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 CREATE_TEMP_INDE
20150 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 X 3 /* Ind
20160 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
20170 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
20180 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
20190 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 REATE_TEMP_TABLE
201a0 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 4 /* Tabl
201b0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
201c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
201d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
201e0 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 EATE_TEMP_TRIGGE
201f0 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 R 5 /* Trigg
20200 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
20210 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
20220 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
20230 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 ATE_TEMP_VIEW
20240 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 6 /* View N
20250 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
20260 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
20270 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
20280 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 TE_TRIGGER
20290 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 7 /* Trigger
202a0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
202b0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
202c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
202d0 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 E_VIEW
202e0 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 8 /* View Nam
202f0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
20300 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
20310 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 ne SQLITE_DELETE
20320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20330 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 9 /* Table Nam
20340 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
20350 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
20360 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e e SQLITE_DROP_IN
20370 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 DEX 10
20380 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
20390 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
203a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
203b0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 SQLITE_DROP_TAB
203c0 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 LE 11
203d0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
203e0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
203f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
20400 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
20410 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 _INDEX 12
20420 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
20430 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
20440 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
20450 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
20460 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 TABLE 13
20470 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
20480 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
20490 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
204a0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 LITE_DROP_TEMP_T
204b0 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f RIGGER 14 /
204c0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
204d0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
204e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
204f0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 ITE_DROP_TEMP_VI
20500 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a EW 15 /*
20510 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
20520 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
20530 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20540 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 TE_DROP_TRIGGER
20550 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 16 /*
20560 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
20570 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
20580 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20590 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 E_DROP_VIEW
205a0 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 17 /* V
205b0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
205c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
205d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
205e0 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 _INSERT
205f0 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 18 /* Ta
20600 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
20610 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
20620 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20630 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 PRAGMA
20640 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 19 /* Pra
20650 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 gma Name 1st
20660 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a arg or NULL */.
20670 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
20680 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 EAD
20690 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 20 /* Tabl
206a0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 e Name Colu
206b0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 mn Name */.#
206c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 define SQLITE_SE
206d0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 LECT
206e0 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 21 /* NULL
206f0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 NULL
20700 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
20710 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 efine SQLITE_TRA
20720 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 NSACTION
20730 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 22 /* Operat
20740 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ion NULL
20750 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
20760 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 fine SQLITE_UPDA
20770 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
20780 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 23 /* Table N
20790 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 ame Column
207a0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
207b0 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 ine SQLITE_ATTAC
207c0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
207d0 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 24 /* Filename
207e0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 NULL
207f0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
20800 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 ne SQLITE_DETACH
20810 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
20820 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 5 /* Database
20830 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 Name NULL
20840 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
20850 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 e SQLITE_ALTER_T
20860 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 ABLE 26
20870 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e /* Database N
20880 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 ame Table Name
20890 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
208a0 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 SQLITE_REINDEX
208b0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 27
208c0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
208d0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
208e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
208f0 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 SQLITE_ANALYZE
20900 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 28
20910 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
20920 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
20930 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
20940 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 QLITE_CREATE_VTA
20950 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 BLE 29
20960 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
20970 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 Module Name
20980 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20990 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 LITE_DROP_VTABLE
209a0 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 30 /
209b0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
209c0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 Module Name
209d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
209e0 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 ITE_FUNCTION
209f0 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 31 /*
20a00 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
20a10 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 Function Name
20a20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20a30 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 TE_SAVEPOINT
20a40 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 32 /*
20a50 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 Operation
20a60 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 Savepoint Name
20a70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20a80 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 E_COPY
20a90 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 0 /* N
20aa0 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f o longer used */
20ab0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20ac0 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 RECURSIVE
20ad0 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 33 /* NUL
20ae0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c L NUL
20af0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
20b00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
20b10 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f Tracing And Pro
20b20 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 filing Functions
20b30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
20b40 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 te3.**.** These
20b50 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 routines registe
20b60 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 r callback funct
20b70 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 ions that can be
20b80 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 used for.** tra
20b90 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 cing and profili
20ba0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e ng the execution
20bb0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e of SQL statemen
20bc0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 ts..**.** ^The c
20bd0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
20be0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 registered by s
20bf0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 qlite3_trace() i
20c00 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 s invoked at.**
20c10 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 various times wh
20c20 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d en an SQL statem
20c30 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e ent is being run
20c40 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 by [sqlite3_ste
20c50 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 p()]..** ^The sq
20c60 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 lite3_trace() ca
20c70 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
20c80 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 d with a UTF-8 r
20c90 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a endering of the.
20ca0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
20cb0 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 text as the sta
20cc0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 tement first beg
20cd0 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a ins executing..*
20ce0 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 * ^(Additional s
20cf0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 qlite3_trace() c
20d00 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f allbacks might o
20d10 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 ccur.** as each
20d20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f triggered subpro
20d30 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e gram is entered.
20d40 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 The callbacks
20d50 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 for triggers.**
20d60 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 contain a UTF-8
20d70 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 SQL comment that
20d80 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 identifies the
20d90 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a trigger.)^.**.**
20da0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 The [SQLITE_TRA
20db0 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 CE_SIZE_LIMIT] c
20dc0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
20dd0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 on can be used t
20de0 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c o limit.** the l
20df0 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 ength of [bound
20e00 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e parameter] expan
20e10 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 sion in the outp
20e20 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 ut of sqlite3_tr
20e30 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ace()..**.** ^Th
20e40 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
20e50 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
20e60 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c y sqlite3_profil
20e70 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
20e80 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 * as each SQL st
20e90 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 atement finishes
20ea0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 . ^The profile
20eb0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e callback contain
20ec0 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 s.** the origina
20ed0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 l statement text
20ee0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 and an estimate
20ef0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 of wall-clock t
20f00 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f ime.** of how lo
20f10 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e ng that statemen
20f20 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 t took to run.
20f30 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c ^The profile cal
20f40 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 lback.** time is
20f50 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e in units of nan
20f60 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 oseconds, howeve
20f70 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d r the current im
20f80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 plementation.**
20f90 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 is only capable
20fa0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 of millisecond r
20fb0 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 esolution so the
20fc0 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 six least signi
20fd0 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 ficant.** digits
20fe0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 in the time are
20ff0 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 meaningless. F
21000 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
21010 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 f SQLite.** migh
21020 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 t provide greate
21030 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 r resolution on
21040 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c the profiler cal
21050 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 lback. The.** s
21060 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 qlite3_profile()
21070 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e function is con
21080 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 sidered experime
21090 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 ntal and is.** s
210a0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
210b0 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 in future versi
210c0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ons of SQLite..*
210d0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
210e0 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 trace(sqlite3*,
210f0 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f void(*xTrace)(vo
21100 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 id*,const char*)
21110 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 , void*);.SQLITE
21120 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f _EXPERIMENTAL vo
21130 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 id *sqlite3_prof
21140 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 ile(sqlite3*,.
21150 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 void(*xProfile)
21160 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 (void*,const cha
21170 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 r*,sqlite3_uint6
21180 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 4), void*);../*.
21190 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 ** CAPI3REF: Que
211a0 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c ry Progress Call
211b0 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a backs.** METHOD:
211c0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
211d0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 The sqlite3_prog
211e0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e ress_handler(D,N
211f0 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 ,X,P) interface
21200 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 causes the callb
21210 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ack.** function
21220 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 X to be invoked
21230 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 periodically dur
21240 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 ing long running
21250 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 calls to.** [sq
21260 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b lite3_exec()], [
21270 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
21280 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 and [sqlite3_get
21290 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a _table()] for.**
212a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
212b0 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d tion D. An exam
212c0 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 ple use for this
212d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
212e0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 to keep a GUI u
212f0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 pdated during a
21300 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a large query..**.
21310 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 ** ^The paramete
21320 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 r P is passed th
21330 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c rough as the onl
21340 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 y parameter to t
21350 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 he .** callback
21360 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 function X. ^Th
21370 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 e parameter N is
21380 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 the approximate
21390 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b number of .** [
213a0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
213b0 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 instructions] th
213c0 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 at are evaluated
213d0 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 between success
213e0 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f ive.** invocatio
213f0 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 ns of the callba
21400 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 ck X. ^If N is
21410 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 less than one th
21420 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a en the progress.
21430 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 ** handler is di
21440 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f sabled..**.** ^O
21450 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f nly a single pro
21460 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 gress handler ma
21470 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 y be defined at
21480 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 one time per.**
21490 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
214a0 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 tion]; setting a
214b0 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 new progress ha
214c0 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 ndler cancels th
214d0 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e e.** old one. ^
214e0 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 Setting paramete
214f0 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 r X to NULL disa
21500 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 bles the progres
21510 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 s handler..** ^T
21520 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
21530 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 ler is also disa
21540 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 bled by setting
21550 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 N to a value les
21560 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a s.** than 1..**.
21570 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 ** ^If the progr
21580 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 ess callback ret
21590 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
215a0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a he operation is.
215b0 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 ** interrupted.
215c0 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 This feature ca
215d0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 n be used to imp
215e0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e lement a.** "Can
215f0 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 cel" button on a
21600 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 GUI progress di
21610 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 alog box..**.**
21620 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e The progress han
21630 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 dler callback mu
21640 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 st not do anythi
21650 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 ng that will mod
21660 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 ify.** the datab
21670 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
21680 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
21690 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
216a0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b ..** Note that [
216b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
216c0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
216d0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 e3_step()] both
216e0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 modify their.**
216f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
21700 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 ions for the mea
21710 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 ning of "modify"
21720 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 in this paragra
21730 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 ph..**.*/.void s
21740 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
21750 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
21760 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f , int, int(*)(vo
21770 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f id*), void*);../
21780 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
21790 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 pening A New Dat
217a0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
217b0 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a .** CONSTRUCTOR:
217c0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
217d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f These routines o
217e0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 pen an SQLite da
217f0 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 tabase file as s
21800 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
21810 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 .** filename arg
21820 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 ument. ^The file
21830 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 name argument is
21840 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
21850 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c UTF-8 for.** sql
21860 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
21870 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
21880 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 ) and as UTF-16
21890 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
218a0 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 te.** order for
218b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
218c0 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 . ^(A [database
218d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
218e0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a le is usually.**
218f0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 returned in *pp
21900 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 Db, even if an e
21910 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 rror occurs. Th
21920 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e e only exception
21930 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 is that.** if S
21940 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 QLite is unable
21950 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f to allocate memo
21960 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b ry to hold the [
21970 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c sqlite3] object,
21980 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 .** a NULL will
21990 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 be written into
219a0 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 *ppDb instead of
219b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
219c0 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f e [sqlite3].** o
219d0 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 bject.)^ ^(If th
219e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
219f0 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 ened (and/or cre
21a00 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c ated) successful
21a10 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c ly, then.** [SQL
21a20 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 ITE_OK] is retur
21a30 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 ned. Otherwise
21a40 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
21a50 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e is returned.)^ ^
21a60 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f The.** [sqlite3_
21a70 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 errmsg()] or [sq
21a80 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
21a90 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 ] routines can b
21aa0 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
21ab0 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c .** an English l
21ac0 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 anguage descript
21ad0 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 ion of the error
21ae0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 following a fai
21af0 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f lure of any.** o
21b00 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 f the sqlite3_op
21b10 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a en() routines..*
21b20 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c *.** ^The defaul
21b30 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 t encoding will
21b40 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 be UTF-8 for dat
21b50 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 abases created u
21b60 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f sing.** sqlite3_
21b70 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
21b80 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 3_open_v2(). ^T
21b90 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 he default encod
21ba0 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 ing for database
21bb0 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 s.** created usi
21bc0 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 ng sqlite3_open1
21bd0 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 6() will be UTF-
21be0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
21bf0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a byte order..**.
21c00 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f ** Whether or no
21c10 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 t an error occur
21c20 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 s when it is ope
21c30 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a ned, resources.*
21c40 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
21c50 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 h the [database
21c60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
21c70 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c le should be rel
21c80 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 eased by.** pass
21c90 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 ing it to [sqlit
21ca0 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e e3_close()] when
21cb0 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 it is no longer
21cc0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
21cd0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 The sqlite3_ope
21ce0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 n_v2() interface
21cf0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
21d00 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 te3_open().** ex
21d10 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 cept that it acc
21d20 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f epts two additio
21d30 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 nal parameters f
21d40 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f or additional co
21d50 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 ntrol.** over th
21d60 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 e new database c
21d70 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 onnection. ^(Th
21d80 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
21d90 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f r to.** sqlite3_
21da0 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 open_v2() can ta
21db0 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 ke one of.** the
21dc0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 following three
21dd0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 values, optiona
21de0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 lly combined wit
21df0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 h the .** [SQLIT
21e00 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c E_OPEN_NOMUTEX],
21e10 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 [SQLITE_OPEN_FU
21e20 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 LLMUTEX], [SQLIT
21e30 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
21e40 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f HE],.** [SQLITE_
21e50 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
21e60 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 E], and/or [SQLI
21e70 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 TE_OPEN_URI] fla
21e80 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e gs:)^.**.** <dl>
21e90 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 .** ^(<dt>[SQLIT
21ea0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
21eb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
21ec0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
21ed0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 ned in read-only
21ee0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 mode. If the d
21ef0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 atabase does not
21f00 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 .** already exis
21f10 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 t, an error is r
21f20 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a eturned.</dd>)^.
21f30 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c **.** ^(<dt>[SQL
21f40 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
21f50 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
21f60 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
21f70 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
21f80 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 ng and writing i
21f90 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 f possible, or r
21fa0 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 eading.** only i
21fb0 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 f the file is wr
21fc0 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 ite protected by
21fd0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
21fe0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 ystem. In eithe
21ff0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 r.** case the da
22000 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 tabase must alre
22010 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 ady exist, other
22020 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 wise an error is
22030 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 returned.</dd>)
22040 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 ^.**.** ^(<dt>[S
22050 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
22060 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f RITE] | [SQLITE_
22070 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 OPEN_CREATE]</dt
22080 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
22090 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
220a0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
220b0 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 writing, and is
220c0 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 created if.** it
220d0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 does not alread
220e0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 y exist. This is
220f0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 the behavior th
22100 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 at is always use
22110 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 d for.** sqlite3
22120 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
22130 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 te3_open16().</d
22140 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a d>)^.** </dl>.**
22150 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 .** If the 3rd p
22160 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
22170 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
22180 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a not one of the.
22190 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 ** combinations
221a0 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 shown above opti
221b0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 onally combined
221c0 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 with other.** [S
221d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
221e0 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 NLY | SQLITE_OPE
221f0 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 N_* bits].** the
22200 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
22210 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
22220 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 ** ^If the [SQLI
22230 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
22240 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 flag is set, th
22250 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
22260 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 connection.** op
22270 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 ens in the multi
22280 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
22290 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 ng mode] as long
222a0 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 as the single-t
222b0 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 hread.** mode ha
222c0 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 s not been set a
222d0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f t compile-time o
222e0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e r start-time. ^
222f0 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 If the.** [SQLIT
22300 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
22310 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 ] flag is set th
22320 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
22330 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 connection opens
22340 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 .** in the seria
22350 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
22360 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 mode] unless si
22370 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a ngle-thread was.
22380 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 ** previously se
22390 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c lected at compil
223a0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d e-time or start-
223b0 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 time..** ^The [S
223c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
223d0 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 DCACHE] flag cau
223e0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ses the database
223f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 connection to b
22400 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f e.** eligible to
22410 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 use [shared cac
22420 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 he mode], regard
22430 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
22440 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a or not shared.**
22450 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 cache is enable
22460 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
22470 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 _enable_shared_c
22480 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a ache()]. ^The.*
22490 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 * [SQLITE_OPEN_P
224a0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 RIVATECACHE] fla
224b0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 g causes the dat
224c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
224d0 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 to not.** parti
224e0 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 cipate in [share
224f0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 d cache mode] ev
22500 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 en if it is enab
22510 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 led..**.** ^The
22520 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
22530 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
22540 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d _v2() is the nam
22550 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c e of the.** [sql
22560 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
22570 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 that defines th
22580 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
22590 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 em interface tha
225a0 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 t.** the new dat
225b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
225c0 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 should use. ^I
225d0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
225e0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e ameter is.** a N
225f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
22600 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
22610 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
22620 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a t is used..**.**
22630 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d ^If the filenam
22640 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c e is ":memory:",
22650 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c then a private,
22660 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 temporary in-me
22670 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a mory database.**
22680 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 is created for
22690 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 the connection.
226a0 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 ^This in-memory
226b0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 database will v
226c0 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 anish when.** th
226d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
226e0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e ction is closed.
226f0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
22700 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
22710 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 t.** make use of
22720 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 additional spec
22730 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 ial filenames th
22740 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 at begin with th
22750 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e e ":" character.
22760 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d .** It is recomm
22770 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 ended that when
22780 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e a database filen
22790 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 ame actually doe
227a0 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 s begin with.**
227b0 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 a ":" character
227c0 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 you should prefi
227d0 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 x the filename w
227e0 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 ith a pathname s
227f0 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 uch as.** "./" t
22800 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 o avoid ambiguit
22810 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 y..**.** ^If the
22820 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 filename is an
22830 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 empty string, th
22840 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 en a private, te
22850 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 mporary.** on-di
22860 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c sk database will
22870 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 be created. ^T
22880 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 his private data
22890 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 base will be.**
228a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 automatically de
228b0 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 leted as soon as
228c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
228d0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 nnection is clos
228e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 ed..**.** [[URI
228f0 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c filenames in sql
22900 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 ite3_open()]] <h
22910 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 3>URI Filenames<
22920 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b /h3>.**.** ^If [
22930 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e URI filename] in
22940 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 terpretation is
22950 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 enabled, and the
22960 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
22970 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 nt.** begins wit
22980 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 h "file:", then
22990 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
229a0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
229b0 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 URI. ^URI.** fi
229c0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 lename interpret
229d0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ation is enabled
229e0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f if the [SQLITE_
229f0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 OPEN_URI] flag i
22a00 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 s.** set in the
22a10 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 fourth argument
22a20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
22a30 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 v2(), or if it h
22a40 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c as.** been enabl
22a50 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e ed globally usin
22a60 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f g the [SQLITE_CO
22a70 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e NFIG_URI] option
22a80 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 with the.** [sq
22a90 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
22aa0 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 method or by the
22ab0 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 [SQLITE_USE_URI
22ac0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
22ad0 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 ption..** As of
22ae0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
22af0 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 .7.7, URI filena
22b00 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f me interpretatio
22b10 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a n is turned off.
22b20 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 ** by default, b
22b30 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 ut future releas
22b40 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 es of SQLite mig
22b50 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 ht enable URI fi
22b60 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 lename.** interp
22b70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 retation by defa
22b80 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 ult. See "[URI
22b90 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 filenames]" for
22ba0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
22bb0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
22bc0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 URI filenames a
22bd0 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 re parsed accord
22be0 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e ing to RFC 3986.
22bf0 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e ^If the URI con
22c00 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 tains an.** auth
22c10 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d ority, then it m
22c20 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e ust be either an
22c30 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 empty string or
22c40 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 the string .**
22c50 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 "localhost". ^If
22c60 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 the authority i
22c70 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 s not an empty s
22c80 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 tring or "localh
22c90 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 ost", an .** err
22ca0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 or is returned t
22cb0 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 o the caller. ^T
22cc0 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 he fragment comp
22cd0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 onent of a URI,
22ce0 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 if .** present,
22cf0 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a is ignored..**.*
22d00 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 * ^SQLite uses t
22d10 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e he path componen
22d20 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 t of the URI as
22d30 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
22d40 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 disk file.** whi
22d50 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 ch contains the
22d60 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 database. ^If th
22d70 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 e path begins wi
22d80 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 th a '/' charact
22d90 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 er, .** then it
22da0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
22db0 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 s an absolute pa
22dc0 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 th. ^If the path
22dd0 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 does not begin
22de0 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 .** with a '/' (
22df0 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 meaning that the
22e00 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 authority secti
22e10 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 on is omitted fr
22e20 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 om the URI).** t
22e30 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 hen the path is
22e40 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
22e50 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 relative path.
22e60 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 .** ^(On windows
22e70 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 , the first comp
22e80 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f onent of an abso
22e90 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 lute path .** is
22ea0 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 a drive specifi
22eb0 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a cation (e.g. "C:
22ec0 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f ").)^.**.** [[co
22ed0 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 re URI query par
22ee0 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 ameters]].** The
22ef0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
22f00 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f of a URI may co
22f10 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 ntain parameters
22f20 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 that are interp
22f30 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 reted.** either
22f40 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 by SQLite itself
22f50 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c , or by a [VFS |
22f60 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c custom VFS impl
22f70 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 ementation]..**
22f80 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 SQLite and its b
22f90 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 uilt-in [VFSes]
22fa0 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a interpret the.**
22fb0 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 following query
22fc0 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a parameters:.**.
22fd0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 ** <ul>.** <li
22fe0 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 > <b>vfs</b>: ^T
22ff0 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 he "vfs" paramet
23000 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 er may be used t
23010 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 o specify the na
23020 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 me of.** a V
23030 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 FS object that p
23040 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 rovides the oper
23050 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 ating system int
23060 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 erface that shou
23070 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 ld.** be use
23080 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 d to access the
23090 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e database file on
230a0 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 disk. ^If this
230b0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f option is set to
230c0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 .** an empty
230d0 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 string the defa
230e0 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 ult VFS object i
230f0 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 s used. ^Specify
23100 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a ing an unknown.*
23110 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 * VFS is an
23120 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 error. ^If sqlit
23130 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
23140 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 used and the vfs
23150 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 option is.**
23160 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 present, then
23170 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 the VFS specifie
23180 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 d by the option
23190 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 takes precedence
231a0 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 over.** the
231b0 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 value passed as
231c0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
231d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
231e0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a _open_v2()..**.*
231f0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 * <li> <b>mode
23200 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 </b>: ^(The mode
23210 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
23220 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 e set to either
23230 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 "ro", "rw",.**
23240 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 "rwc", or "me
23250 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e mory". Attemptin
23260 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 g to set it to a
23270 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 ny other value i
23280 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f s.** an erro
23290 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 r)^. .** ^If
232a0 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 "ro" is specifi
232b0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 ed, then the dat
232c0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
232d0 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a for read-only .*
232e0 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 * access, ju
232f0 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 st as if the [SQ
23300 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
23310 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 LY] flag had bee
23320 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a n set in the .**
23330 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d third argum
23340 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ent to sqlite3_o
23350 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 pen_v2(). ^If th
23360 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 e mode option is
23370 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 set to .**
23380 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 "rw", then the d
23390 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
233a0 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 d for read-write
233b0 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 (but not create
233c0 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 ) .** access
233d0 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f , as if SQLITE_O
233e0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 PEN_READWRITE (b
233f0 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 ut not SQLITE_OP
23400 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a EN_CREATE) had .
23410 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e ** been set.
23420 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 ^Value "rwc" is
23430 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 equivalent to s
23440 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 etting both .**
23450 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f SQLITE_OPEN_
23460 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 READWRITE and SQ
23470 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
23480 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 . ^If the mode
23490 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 option is.**
234a0 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 set to "memory"
234b0 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e then a pure [in
234c0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
234d0 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 ] that never rea
234e0 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 ds.** or wri
234f0 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 tes from disk is
23500 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e used. ^It is an
23510 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 error to specif
23520 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a y a value for.**
23530 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 the mode pa
23540 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 rameter that is
23550 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 less restrictive
23560 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 than that speci
23570 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 fied by.** t
23580 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 he flags passed
23590 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 in the third par
235a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
235b0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 3_open_v2()..**.
235c0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 ** <li> <b>cac
235d0 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 he</b>: ^The cac
235e0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 he parameter may
235f0 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 be set to eithe
23600 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a r "shared" or.**
23610 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 "private".
23620 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 ^Setting it to "
23630 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 shared" is equiv
23640 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 alent to setting
23650 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 the.** SQLI
23660 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
23670 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 CHE bit in the f
23680 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 lags argument pa
23690 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 ssed to.** s
236a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
236b0 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 . ^Setting the c
236c0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 ache parameter t
236d0 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a o "private" is .
236e0 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e ** equivalen
236f0 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 t to setting the
23700 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 SQLITE_OPEN_PRI
23710 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a VATECACHE bit..*
23720 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 * ^If sqlite
23730 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 3_open_v2() is u
23740 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 sed and the "cac
23750 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 he" parameter is
23760 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 present in.**
23770 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d a URI filenam
23780 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 e, its value ove
23790 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 rrides any behav
237a0 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 ior requested by
237b0 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 setting.**
237c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
237d0 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 ATECACHE or SQLI
237e0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
237f0 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 CHE flag..**.**
23800 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 <li> <b>psow</b
23810 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 >: ^The psow par
23820 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 ameter indicates
23830 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
23840 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 the.** [powe
23850 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d rsafe overwrite]
23860 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f property does o
23870 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 r does not apply
23880 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 to the.** s
23890 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 torage media on
238a0 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 which the databa
238b0 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e se file resides.
238c0 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e .**.** <li> <b>
238d0 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 nolock</b>: ^The
238e0 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 nolock paramete
238f0 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 r is a boolean q
23900 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a uery parameter.*
23910 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 * which if s
23920 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 et disables file
23930 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c locking in roll
23940 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 back journal mod
23950 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 es. This.**
23960 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 is useful for a
23970 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 ccessing a datab
23980 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 ase on a filesys
23990 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f tem that does no
239a0 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 t.** support
239b0 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 locking. Cauti
239c0 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f on: Database co
239d0 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 rruption might r
239e0 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 esult if two.**
239f0 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 or more proc
23a00 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 esses write to t
23a10 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
23a20 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 and any one of
23a30 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f those.** pro
23a40 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f cesses uses nolo
23a50 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 ck=1..**.** <li
23a60 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f > <b>immutable</
23a70 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 b>: ^The immutab
23a80 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 le parameter is
23a90 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a a boolean query.
23aa0 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 ** parameter
23ab0 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 that indicates
23ac0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 that the databas
23ad0 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 e file is stored
23ae0 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d on.** read-
23af0 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 only media. ^Wh
23b00 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 en immutable is
23b10 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 set, SQLite assu
23b20 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 mes that the.**
23b30 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c database fil
23b40 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e e cannot be chan
23b50 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 ged, even by a p
23b60 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 rocess with high
23b70 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c er.** privil
23b80 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 ege, and so the
23b90 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
23ba0 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 ed read-only and
23bb0 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 all locking.**
23bc0 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 and change d
23bd0 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 etection is disa
23be0 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 bled. Caution:
23bf0 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 Setting the immu
23c00 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f table.** pro
23c10 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 perty on a datab
23c20 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f ase file that do
23c30 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 es in fact chang
23c40 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 e can result.**
23c50 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 in incorrect
23c60 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 query results a
23c70 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f nd/or [SQLITE_CO
23c80 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a RRUPT] errors..*
23c90 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 * See also:
23ca0 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d [SQLITE_IOCAP_IM
23cb0 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 MUTABLE]..**
23cc0 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a .** </ul>.**.
23cd0 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 ** ^Specifying a
23ce0 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 n unknown parame
23cf0 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 ter in the query
23d00 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 component of a
23d10 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a URI is not an.**
23d20 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 error. Future
23d30 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
23d40 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 te might underst
23d50 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 and additional q
23d60 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 uery.** paramete
23d70 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 rs. See "[query
23d80 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 parameters with
23d90 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 special meaning
23da0 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 to SQLite]" for
23db0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 .** additional i
23dc0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
23dd0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 * [[URI filename
23de0 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e examples]] <h3>
23df0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 URI filename exa
23e00 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a mples</h3>.**.**
23e10 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 <table border="
23e20 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 1" align=center
23e30 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a cellpadding=5>.*
23e40 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 * <tr><th> URI f
23e50 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 ilenames <th> Re
23e60 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 sults.** <tr><td
23e70 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c > file:data.db <
23e80 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
23e90 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 Open the file "
23ea0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 data.db" in the
23eb0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 current director
23ec0 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 y..** <tr><td> f
23ed0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 ile:/home/fred/d
23ee0 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 ata.db<br>.**
23ef0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 file:///h
23f00 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
23f10 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <br> .**
23f20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 file://localh
23f30 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 ost/home/fred/da
23f40 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 ta.db <br> <td>
23f50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 .** Ope
23f60 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 n the database f
23f70 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f ile "/home/fred/
23f80 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 data.db"..** <tr
23f90 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 ><td> file://dar
23fa0 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f kstar/home/fred/
23fb0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a data.db <td> .**
23fc0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 An err
23fd0 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 or. "darkstar" i
23fe0 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a s not a recogniz
23ff0 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a ed authority..**
24000 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 <tr><td style="
24010 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 white-space:nowr
24020 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 ap"> .**
24030 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 file:///C:/Doc
24040 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 uments%20and%20S
24050 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 ettings/fred/Des
24060 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 ktop/data.db.**
24070 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 <td> Windows
24080 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 only: Open the
24090 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f file "data.db" o
240a0 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 n fred's desktop
240b0 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 on drive.**
240c0 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 C:. Note t
240d0 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 hat the %20 esca
240e0 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 ping in this exa
240f0 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 mple is not stri
24100 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 ctly .**
24110 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 necessary - sp
24120 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 ace characters c
24130 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 an be used liter
24140 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 ally.**
24150 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 in URI filename
24160 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 s..** <tr><td> f
24170 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 ile:data.db?mode
24180 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 =ro&cache=privat
24190 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 e <td> .**
241a0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 Open file "d
241b0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 ata.db" in the c
241c0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 urrent directory
241d0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 for read-only a
241e0 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 ccess..**
241f0 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 Regardless of
24200 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
24210 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 shared-cache mod
24220 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a e is enabled by.
24230 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 ** defa
24240 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 ult, use a priva
24250 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 te cache..** <tr
24260 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 ><td> file:/home
24270 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 /fred/data.db?vf
24280 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c s=unix-dotfile <
24290 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 td>.**
242a0 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 Open file "/home
242b0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 /fred/data.db".
242c0 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 Use the special
242d0 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c VFS "unix-dotfil
242e0 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 e".** t
242f0 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c hat uses dot-fil
24300 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 es in place of p
24310 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f osix advisory lo
24320 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 cking..** <tr><t
24330 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f d> file:data.db?
24340 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 mode=readonly <t
24350 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
24360 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f An error. "reado
24370 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 nly" is not a va
24380 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 lid option for t
24390 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 he "mode" parame
243a0 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e ter..** </table>
243b0 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 .**.** ^URI hexa
243c0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 decimal escape s
243d0 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 equences (%HH) a
243e0 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 re supported wit
243f0 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 hin the path and
24400 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e .** query compon
24410 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 ents of a URI. A
24420 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 hexadecimal esc
24430 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e ape sequence con
24440 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 sists of a.** pe
24450 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 rcent sign - "%"
24460 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 - followed by e
24470 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 xactly two hexad
24480 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a ecimal digits .*
24490 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 * specifying an
244a0 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 octet value. ^Be
244b0 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 fore the path or
244c0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
244d0 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 s of a.** URI fi
244e0 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 lename are inter
244f0 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 preted, they are
24500 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 encoded using U
24510 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a TF-8 and all .**
24520 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 hexadecimal esc
24530 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 ape sequences re
24540 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 placed by a sing
24550 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 le byte containi
24560 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 ng the.** corres
24570 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 ponding octet. I
24580 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 f this process g
24590 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 enerates an inva
245a0 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 lid UTF-8 encodi
245b0 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c ng,.** the resul
245c0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
245d0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 ..**.** <b>Note
245e0 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 to Windows users
245f0 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 :</b> The encod
24600 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 ing used for the
24610 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
24620 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 nt.** of sqlite3
24630 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
24640 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 te3_open_v2() mu
24650 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 st be UTF-8, not
24660 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 whatever.** cod
24670 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 epage is current
24680 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c ly defined. Fil
24690 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e enames containin
246a0 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a g international.
246b0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 ** characters mu
246c0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 st be converted
246d0 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 to UTF-8 prior t
246e0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 o passing them i
246f0 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f nto.** sqlite3_o
24700 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
24710 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a _open_v2()..**.*
24720 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e * <b>Note to Win
24730 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 dows Runtime use
24740 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d rs:</b> The tem
24750 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 porary directory
24760 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 must be set.**
24770 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
24780 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
24790 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
247a0 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 v2(). Otherwise
247b0 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 , various.** fea
247c0 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 tures that requi
247d0 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 re the use of te
247e0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 mporary files ma
247f0 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 y fail..**.** Se
24800 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
24810 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d _temp_directory]
24820 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
24830 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 open(. const ch
24840 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 ar *filename,
24850 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
24860 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a name (UTF-8) */.
24870 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
24880 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
24890 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
248a0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c le */.);.int sql
248b0 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 ite3_open16(. c
248c0 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e onst void *filen
248d0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
248e0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
248f0 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 -16) */. sqlite
24900 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 3 **ppDb
24910 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
24920 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b db handle */.);
24930 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 .int sqlite3_ope
24940 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 n_v2(. const ch
24950 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 ar *filename,
24960 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
24970 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a name (UTF-8) */.
24980 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
24990 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 , /* OUT
249a0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
249b0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 le */. int flag
249c0 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 s,
249d0 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f /* Flags */. co
249e0 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 nst char *zVfs
249f0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 /* Name of
24a00 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 VFS module to u
24a10 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 se */.);../*.**
24a20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e CAPI3REF: Obtain
24a30 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 Values For URI
24a40 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a Parameters.**.**
24a50 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 These are utili
24a60 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 ty routines, use
24a70 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 ful to VFS imple
24a80 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 mentations, that
24a90 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 check.** to see
24aa0 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 if a database f
24ab0 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 ile was a URI th
24ac0 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 at contained a s
24ad0 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a pecific query .*
24ae0 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 * parameter, and
24af0 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 if so obtains t
24b00 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 he value of that
24b10 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
24b20 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 ..**.** If F is
24b30 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
24b40 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 ename pointer pa
24b50 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f ssed into the xO
24b60 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 pen() method of
24b70 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d .** a VFS implem
24b80 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 entation when th
24b90 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
24ba0 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 r to xOpen() has
24bb0 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 one or .** more
24bc0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f of the [SQLITE_
24bd0 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 OPEN_URI] or [SQ
24be0 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 LITE_OPEN_MAIN_D
24bf0 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a B] bits set and.
24c00 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 ** P is the name
24c10 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 of the query pa
24c20 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a rameter, then.**
24c30 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 sqlite3_uri_par
24c40 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 ameter(F,P) retu
24c50 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 rns the value of
24c60 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 the P.** parame
24c70 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 ter if it exists
24c80 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 or a NULL point
24c90 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 er if P does not
24ca0 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a appear as a .**
24cb0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
24cc0 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 on F. If P is
24cd0 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 a query paramete
24ce0 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f r of F.** has no
24cf0 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c explicit value,
24d00 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
24d10 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 i_parameter(F,P)
24d20 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f returns.** a po
24d30 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 inter to an empt
24d40 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 y string..**.**
24d50 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f The sqlite3_uri_
24d60 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 boolean(F,P,B) r
24d70 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 outine assumes t
24d80 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 hat P is a boole
24d90 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 an.** parameter
24da0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 and returns true
24db0 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 (1) or false (0
24dc0 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 ) according to t
24dd0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 he value.** of P
24de0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 . The sqlite3_u
24df0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
24e00 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
24e10 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 s true (1) if th
24e20 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 e.** value of qu
24e30 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 ery parameter P
24e40 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c is one of "yes",
24e50 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 "true", or "on"
24e60 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 in any.** case
24e70 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 or if the value
24e80 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f begins with a no
24e90 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 n-zero number.
24ea0 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f The .** sqlite3_
24eb0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
24ec0 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 B) routines retu
24ed0 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 rns false (0) if
24ee0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a the value of.**
24ef0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
24f00 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f P is one of "no
24f10 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 ", "false", or "
24f20 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 off" in any case
24f30 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 or.** if the va
24f40 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 lue begins with
24f50 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 a numeric zero.
24f60 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 If P is not a q
24f70 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 uery.** paramete
24f80 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 r on F or if the
24f90 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 value of P is d
24fa0 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e oes not match an
24fb0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 y of the.** abov
24fc0 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f e, then sqlite3_
24fd0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
24fe0 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 B) returns (B!=0
24ff0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )..**.** The sql
25000 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 ite3_uri_int64(F
25010 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f ,P,D) routine co
25020 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 nverts the value
25030 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 of P into a.**
25040 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
25050 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e teger and return
25060 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 s that integer,
25070 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e or D if P does n
25080 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 ot.** exist. If
25090 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
250a0 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 is something oth
250b0 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 er than an integ
250c0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f er, then.** zero
250d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
250e0 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e .** If F is a N
250f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
25100 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 n sqlite3_uri_pa
25110 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 rameter(F,P) ret
25120 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a urns NULL and.**
25130 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
25140 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 lean(F,P,B) retu
25150 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 rns B. If F is
25160 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 not a NULL point
25170 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 er and.** is not
25180 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
25190 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 pathname pointe
251a0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 r that SQLite pa
251b0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f ssed into the xO
251c0 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f pen.** VFS metho
251d0 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 d, then the beha
251e0 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 vior of this rou
251f0 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 tine is undefine
25200 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a d and probably.*
25210 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a * undesirable..*
25220 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
25230 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 lite3_uri_parame
25240 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a ter(const char *
25250 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 zFilename, const
25260 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a char *zParam);.
25270 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f int sqlite3_uri_
25280 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 boolean(const ch
25290 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 ar *zFile, const
252a0 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 char *zParam, i
252b0 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 nt bDefault);.sq
252c0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
252d0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f te3_uri_int64(co
252e0 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 nst char*, const
252f0 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f char*, sqlite3_
25300 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 int64);.../*.**
25310 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 CAPI3REF: Error
25320 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 Codes And Messag
25330 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 es.** METHOD: sq
25340 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 lite3.**.** ^If
25350 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
25360 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 sqlite3_* API ca
25370 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ll associated wi
25380 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 th .** [database
25390 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 connection] D f
253a0 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 ailed, then the
253b0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
253c0 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 D) interface.**
253d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 returns the nume
253e0 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 ric [result code
253f0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 ] or [extended r
25400 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 esult code] for
25410 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c that.** API call
25420 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 ..** If the most
25430 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c recent API call
25440 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c was successful,
25450 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 .** then the ret
25460 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 urn value from s
25470 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
25480 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
25490 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
254a0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 xtended_errcode(
254b0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 ).** interface i
254c0 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 s the same excep
254d0 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 t that it always
254e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a returns the .**
254f0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
25500 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 t code] even whe
25510 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c n extended resul
25520 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 t codes are.** d
25530 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e isabled..**.** ^
25540 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d The sqlite3_errm
25550 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 sg() and sqlite3
25560 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 _errmsg16() retu
25570 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 rn English-langu
25580 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 age.** text that
25590 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 describes the e
255a0 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 rror, as either
255b0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 UTF-8 or UTF-16
255c0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a respectively..**
255d0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c ^(Memory to hol
255e0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 d the error mess
255f0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 age string is ma
25600 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 naged internally
25610 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
25620 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 tion does not ne
25630 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 ed to worry abou
25640 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 t freeing the re
25650 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 sult..** However
25660 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 , the error stri
25670 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 ng might be over
25680 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c written or deall
25690 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 ocated by.** sub
256a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
256b0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
256c0 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e terface function
256d0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 s.)^.**.** ^The
256e0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 sqlite3_errstr()
256f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
25700 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c ns the English-l
25710 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 anguage text.**
25720 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 that describes t
25730 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d he [result code]
25740 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e , as UTF-8..** ^
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 0a 2a ged internally.*
25790 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 * and must not b
257a0 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 e freed by the a
257b0 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a pplication)^..**
257c0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 .** When the ser
257d0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
257e0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 ng mode] is in u
257f0 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 se, it might be
25800 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 the.** case that
25810 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 a second error
25820 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 occurs on a sepa
25830 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 rate thread in b
25840 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 etween.** the ti
25850 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 me of the first
25860 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 error and the ca
25870 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 ll to these inte
25880 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 rfaces..** When
25890 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 that happens, th
258a0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 e second error w
258b0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 ill be reported
258c0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 since these.** i
258d0 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 nterfaces always
258e0 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 report the most
258f0 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 recent result.
25900 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 To avoid.** thi
25910 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 s, each thread c
25920 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 an obtain exclus
25930 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b ive use of the [
25940 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
25950 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 ion] D.** by inv
25960 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d oking [sqlite3_m
25970 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c utex_enter]([sql
25980 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 ite3_db_mutex](D
25990 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e )) before beginn
259a0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 ing.** to use D
259b0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 and invoking [sq
259c0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 lite3_mutex_leav
259d0 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d e]([sqlite3_db_m
259e0 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a utex](D)) after.
259f0 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 ** all calls to
25a00 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c the interfaces l
25a10 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 isted here are c
25a20 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 ompleted..**.**
25a30 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 If an interface
25a40 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 fails with SQLIT
25a50 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d E_MISUSE, that m
25a60 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 eans the interfa
25a70 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 ce.** was invoke
25a80 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 d incorrectly by
25a90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
25aa0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c . In that case,
25ab0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f the.** error co
25ac0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d de and message m
25ad0 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 ay or may not be
25ae0 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c set..*/.int sql
25af0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c ite3_errcode(sql
25b00 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 ite3 *db);.int s
25b10 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
25b20 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 errcode(sqlite3
25b30 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 *db);.const char
25b40 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 *sqlite3_errmsg
25b50 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 (sqlite3*);.cons
25b60 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
25b70 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 errmsg16(sqlite3
25b80 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a *);.const char *
25b90 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 sqlite3_errstr(i
25ba0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
25bb0 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 3REF: Prepared S
25bc0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a tatement Object.
25bd0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 ** KEYWORDS: {pr
25be0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
25bf0 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 } {prepared stat
25c00 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e ements}.**.** An
25c10 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
25c20 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 s object represe
25c30 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c nts a single SQL
25c40 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a statement that.
25c50 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 ** has been comp
25c60 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 iled into binary
25c70 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 form and is rea
25c80 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 dy to be evaluat
25c90 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 ed..**.** Think
25ca0 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 of each SQL stat
25cb0 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 ement as a separ
25cc0 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f ate computer pro
25cd0 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 gram. The.** or
25ce0 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 iginal SQL text
25cf0 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 is source code.
25d00 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 A prepared stat
25d10 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a ement object .**
25d20 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 is the compiled
25d30 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 object code. A
25d40 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 ll SQL must be c
25d50 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a onverted into a.
25d60 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ** prepared stat
25d70 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 ement before it
25d80 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a can be run..**.*
25d90 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 * The life-cycle
25da0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 of a prepared s
25db0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
25dc0 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b usually goes lik
25dd0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f e this:.**.** <o
25de0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 l>.** <li> Creat
25df0 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 e the prepared s
25e00 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
25e10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 using [sqlite3_p
25e20 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a repare_v2()]..**
25e30 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 <li> Bind value
25e40 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 s to [parameters
25e50 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 ] using the sqli
25e60 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 te3_bind_*().**
25e70 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e interfaces.
25e80 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 .** <li> Run the
25e90 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 SQL by calling
25ea0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
25eb0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
25ec0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 es..** <li> Rese
25ed0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 t the prepared s
25ee0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
25ef0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
25f00 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a then go back.**
25f10 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e to step 2.
25f20 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f Do this zero o
25f30 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a r more times..**
25f40 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 <li> Destroy th
25f50 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b e object using [
25f60 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
25f70 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f ()]..** </ol>.*/
25f80 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
25f90 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c sqlite3_stmt sql
25fa0 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a ite3_stmt;../*.*
25fb0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
25fc0 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d time Limits.** M
25fd0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
25fe0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 *.** ^(This inte
25ff0 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 rface allows the
26000 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 size of various
26010 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 constructs to b
26020 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 e limited.** on
26030 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 a connection by
26040 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 connection basis
26050 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 . The first par
26060 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
26070 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
26080 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d ction] whose lim
26090 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 it is to be set
260a0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 or queried. The
260b0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
260c0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 eter is one of t
260d0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f he [limit catego
260e0 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e ries] that defin
260f0 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 e a.** class of
26100 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 constructs to be
26110 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 size limited.
26120 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
26130 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 ter is the.** ne
26140 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 w limit for that
26150 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a construct.)^.**
26160 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 .** ^If the new
26170 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 limit is a negat
26180 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 ive number, the
26190 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 limit is unchang
261a0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 ed..** ^(For eac
261b0 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 h limit category
261c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 SQLITE_LIMIT_<i
261d0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 >NAME</i> there
261e0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 is a .** [limits
261f0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f | hard upper bo
26200 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 und].** set at c
26210 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 ompile-time by a
26220 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
26230 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 macro called.**
26240 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 [limits | SQLITE
26250 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e _MAX_<i>NAME</i>
26260 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d ]..** (The "_LIM
26270 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 IT_" in the name
26280 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 is changed to "
26290 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 _MAX_".))^.** ^A
262a0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 ttempts to incre
262b0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 ase a limit abov
262c0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 e its hard upper
262d0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 bound are.** si
262e0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 lently truncated
262f0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 to the hard upp
26300 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 er bound..**.**
26310 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 ^Regardless of w
26320 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
26330 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e e limit was chan
26340 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 ged, the .** [sq
26350 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 lite3_limit()] i
26360 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
26370 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 the prior value
26380 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a of the limit..*
26390 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e * ^Hence, to fin
263a0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 d the current va
263b0 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 lue of a limit w
263c0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 ithout changing
263d0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e it,.** simply in
263e0 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 voke this interf
263f0 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 ace with the thi
26400 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 rd parameter set
26410 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 to -1..**.** Ru
26420 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 n-time limits ar
26430 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 e intended for u
26440 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f se in applicatio
26450 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a ns that manage.*
26460 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e * both their own
26470 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 internal databa
26480 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 se and also data
26490 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 bases that are c
264a0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 ontrolled.** by
264b0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e untrusted extern
264c0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 al sources. An
264d0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 example applicat
264e0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a ion might be a.*
264f0 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 * web browser th
26500 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 at has its own d
26510 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f atabases for sto
26520 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 ring history and
26530 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 .** separate dat
26540 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 abases controlle
26550 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 d by JavaScript
26560 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 applications dow
26570 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 nloaded.** off t
26580 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 he Internet. Th
26590 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 e internal datab
265a0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 ases can be give
265b0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 n the.** large,
265c0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 default limits.
265d0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 Databases manag
265e0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 ed by external s
265f0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 ources can.** be
26600 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c given much smal
26610 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 ler limits desig
26620 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 ned to prevent a
26630 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 denial of servi
26640 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 ce.** attack. D
26650 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 evelopers might
26660 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 also want to use
26670 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 the [sqlite3_se
26680 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a t_authorizer()].
26690 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 ** interface to
266a0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 further control
266b0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 untrusted SQL.
266c0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 The size of the
266d0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 database.** crea
266e0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 ted by an untrus
266f0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 ted script can b
26700 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e e contained usin
26710 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 g the.** [max_pa
26720 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d ge_count] [PRAGM
26730 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 A]..**.** New ru
26740 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 n-time limit cat
26750 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 egories may be a
26760 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
26770 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 eleases..*/.int
26780 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 sqlite3_limit(sq
26790 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 lite3*, int id,
267a0 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a int newVal);../*
267b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 .** CAPI3REF: Ru
267c0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 n-Time Limit Cat
267d0 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f egories.** KEYWO
267e0 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 RDS: {limit cate
267f0 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 gory} {*limit ca
26800 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 tegories}.**.**
26810 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
26820 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 define various p
26830 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 erformance limit
26840 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 s.** that can be
26850 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d lowered at run-
26860 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 time using [sqli
26870 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a te3_limit()]..**
26880 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 The synopsis of
26890 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 the meanings of
268a0 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d the various lim
268b0 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c its is shown bel
268c0 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 ow..** Additiona
268d0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 l information is
268e0 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c available at [l
268f0 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 imits | Limits i
26900 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a n SQLite]..**.**
26910 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 <dl>.** [[SQLIT
26920 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d E_LIMIT_LENGTH]]
26930 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
26940 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a MIT_LENGTH</dt>.
26950 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
26960 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 um size of any s
26970 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 tring or BLOB or
26980 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 table row, in b
26990 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a ytes.<dd>)^.**.*
269a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
269b0 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 _SQL_LENGTH]] ^(
269c0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
269d0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e _SQL_LENGTH</dt>
269e0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
269f0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e mum length of an
26a00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
26a10 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e in bytes.</dd>)^
26a20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
26a30 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e LIMIT_COLUMN]] ^
26a40 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
26a50 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a T_COLUMN</dt>.**
26a60 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
26a70 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
26a80 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 ns in a table de
26a90 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 finition or in t
26aa0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 he.** result set
26ab0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f of a [SELECT] o
26ac0 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 r the maximum nu
26ad0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
26ae0 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f in an index.** o
26af0 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 r in an ORDER BY
26b00 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 or GROUP BY cla
26b10 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a use.</dd>)^.**.*
26b20 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
26b30 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 _EXPR_DEPTH]] ^(
26b40 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
26b50 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e _EXPR_DEPTH</dt>
26b60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
26b70 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 mum depth of the
26b80 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 parse tree on a
26b90 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f ny expression.</
26ba0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
26bb0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f LITE_LIMIT_COMPO
26bc0 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c UND_SELECT]] ^(<
26bd0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
26be0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c COMPOUND_SELECT<
26bf0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
26c00 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
26c10 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d f terms in a com
26c20 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 pound SELECT sta
26c30 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a tement.</dd>)^.*
26c40 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
26c50 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 MIT_VDBE_OP]] ^(
26c60 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
26c70 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a _VDBE_OP</dt>.**
26c80 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
26c90 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 number of instr
26ca0 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 uctions in a vir
26cb0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f tual machine pro
26cc0 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 gram.** used to
26cd0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c implement an SQL
26ce0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 statement. Thi
26cf0 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 s limit is not c
26d00 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f urrently.** enfo
26d10 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 rced, though tha
26d20 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 t might be added
26d30 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 in some future
26d40 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 release of.** SQ
26d50 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a Lite.</dd>)^.**.
26d60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
26d70 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d T_FUNCTION_ARG]]
26d80 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
26d90 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 MIT_FUNCTION_ARG
26da0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
26db0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
26dc0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 of arguments on
26dd0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e a function.</dd>
26de0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
26df0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 E_LIMIT_ATTACHED
26e00 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
26e10 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f LIMIT_ATTACHED</
26e20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
26e30 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
26e40 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 [ATTACH | attac
26e50 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 hed databases].)
26e60 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 ^</dd>.**.** [[S
26e70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 QLITE_LIMIT_LIKE
26e80 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d _PATTERN_LENGTH]
26e90 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 ].** ^(<dt>SQLIT
26ea0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 E_LIMIT_LIKE_PAT
26eb0 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e TERN_LENGTH</dt>
26ec0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
26ed0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 mum length of th
26ee0 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 e pattern argume
26ef0 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d nt to the [LIKE]
26f00 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 or.** [GLOB] op
26f10 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a erators.</dd>)^.
26f20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
26f30 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
26f40 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e MBER]].** ^(<dt>
26f50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
26f60 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 IABLE_NUMBER</dt
26f70 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
26f80 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 imum index numbe
26f90 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 r of any [parame
26fa0 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 ter] in an SQL s
26fb0 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a tatement.)^.**.*
26fc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
26fd0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d _TRIGGER_DEPTH]]
26fe0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
26ff0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 MIT_TRIGGER_DEPT
27000 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
27010 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 e maximum depth
27020 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 of recursion for
27030 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 triggers.</dd>)
27040 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
27050 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 _LIMIT_WORKER_TH
27060 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 READS]] ^(<dt>SQ
27070 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 LITE_LIMIT_WORKE
27080 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a R_THREADS</dt>.*
27090 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
270a0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 m number of auxi
270b0 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 liary worker thr
270c0 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 eads that a sing
270d0 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 le.** [prepared
270e0 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 statement] may s
270f0 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 tart.</dd>)^.**
27100 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
27110 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 SQLITE_LIMIT_LE
27120 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 NGTH
27130 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 0.#defin
27140 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 e SQLITE_LIMIT_S
27150 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 QL_LENGTH
27160 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 1.#defi
27170 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
27180 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 COLUMN
27190 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 2.#def
271a0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
271b0 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 _EXPR_DEPTH
271c0 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 3.#de
271d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
271e0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 T_COMPOUND_SELEC
271f0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 T 4.#d
27200 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
27210 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 IT_VDBE_OP
27220 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 5.#
27230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
27240 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 MIT_FUNCTION_ARG
27250 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 6.
27260 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
27270 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 IMIT_ATTACHED
27280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 7
27290 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
272a0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
272b0 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 RN_LENGTH
272c0 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
272d0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
272e0 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 NUMBER
272f0 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 9.#define SQLIT
27300 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f E_LIMIT_TRIGGER_
27310 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 DEPTH
27320 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 10.#define SQLI
27330 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f TE_LIMIT_WORKER_
27340 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20 THREADS
27350 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 11../*.** CAPI
27360 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 3REF: Compiling
27370 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
27380 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 .** KEYWORDS: {S
27390 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d QL statement com
273a0 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 piler}.** METHOD
273b0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e : sqlite3.** CON
273c0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 STRUCTOR: sqlite
273d0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 3_stmt.**.** To
273e0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 execute an SQL q
273f0 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 uery, it must fi
27400 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 rst be compiled
27410 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 into a byte-code
27420 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e .** program usin
27430 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 g one of these r
27440 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 outines..**.** T
27450 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
27460 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 t, "db", is a [d
27470 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
27480 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f on] obtained fro
27490 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 m a.** prior suc
274a0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
274b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
274c0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f , [sqlite3_open_
274d0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c v2()] or.** [sql
274e0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 ite3_open16()].
274f0 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f The database co
27500 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f nnection must no
27510 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 t have been clos
27520 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 ed..**.** The se
27530 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 cond argument, "
27540 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 zSql", is the st
27550 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f atement to be co
27560 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a mpiled, encoded.
27570 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 ** as either UTF
27580 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 -8 or UTF-16. T
27590 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
275a0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 re() and sqlite3
275b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a _prepare_v2().**
275c0 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 interfaces use
275d0 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 UTF-8, and sqlit
275e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 e3_prepare16() a
275f0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
27600 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 re16_v2().** use
27610 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e UTF-16..**.** ^
27620 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 If the nByte arg
27630 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 ument is negativ
27640 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 e, then zSql is
27650 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a read up to the.*
27660 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 * first zero ter
27670 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 minator. ^If nBy
27680 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 te is positive,
27690 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a then it is the.*
276a0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 * number of byte
276b0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c s read from zSql
276c0 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 . ^If nByte is
276d0 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 zero, then no pr
276e0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d epared.** statem
276f0 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 ent is generated
27700 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c ..** If the call
27710 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 er knows that th
27720 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e e supplied strin
27730 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 g is nul-termina
27740 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 ted, then.** the
27750 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 re is a small pe
27760 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 rformance advant
27770 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 age to passing a
27780 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 n nByte paramete
27790 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 r that.** is the
277a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
277b0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 in the input st
277c0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e ring <i>includin
277d0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c g</i>.** the nul
277e0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a -terminator..**.
277f0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 ** ^If pzTail is
27800 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a not NULL then *
27810 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 pzTail is made t
27820 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 o point to the f
27830 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 irst byte.** pas
27840 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 t the end of the
27850 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 first SQL state
27860 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 ment in zSql. T
27870 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e hese routines on
27880 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 ly.** compile th
27890 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e e first statemen
278a0 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 t in zSql, so *p
278b0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f zTail is left po
278c0 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 inting to.** wha
278d0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 t remains uncomp
278e0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 iled..**.** ^*pp
278f0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 Stmt is left poi
27900 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 nting to a compi
27910 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 led [prepared st
27920 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 atement] that ca
27930 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 n be.** executed
27940 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
27950 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 step()]. ^If th
27960 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c ere is an error,
27970 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a *ppStmt is set.
27980 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 ** to NULL. ^If
27990 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 the input text
279a0 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 contains no SQL
279b0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 (if the input is
279c0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 an empty.** str
279d0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 ing or a comment
279e0 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 ) then *ppStmt i
279f0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a s set to NULL..*
27a00 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 * The calling pr
27a10 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f ocedure is respo
27a20 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 nsible for delet
27a30 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 ing the compiled
27a40 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
27a50 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
27a60 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 _finalize()] aft
27a70 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 er it has finish
27a80 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 ed with it..** p
27a90 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 pStmt may not be
27aa0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e NULL..**.** ^On
27ab0 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 success, the sq
27ac0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 lite3_prepare()
27ad0 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e family of routin
27ae0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 es return [SQLIT
27af0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 E_OK];.** otherw
27b00 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f ise an [error co
27b10 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
27b20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
27b30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 e3_prepare_v2()
27b40 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
27b50 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 are16_v2() inter
27b60 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 faces are.** rec
27b70 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c ommended for all
27b80 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 new programs. T
27b90 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 he two older int
27ba0 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 erfaces are reta
27bb0 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b ined.** for back
27bc0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
27bd0 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 ity, but their u
27be0 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 se is discourage
27bf0 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 d..** ^In the "v
27c00 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 2" interfaces, t
27c10 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
27c20 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 ement.** that is
27c30 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b returned (the [
27c40 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 sqlite3_stmt] ob
27c50 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 ject) contains a
27c60 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
27c70 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 original SQL tex
27c80 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 t. This causes t
27c90 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
27ca0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f ()] interface to
27cb0 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 .** behave diffe
27cc0 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 rently in three
27cd0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e ways:.**.** <ol>
27ce0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 .** <li>.** ^If
27cf0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 the database sch
27d00 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 ema changes, ins
27d10 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e tead of returnin
27d20 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 g [SQLITE_SCHEMA
27d30 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 ] as it.** alway
27d40 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 s used to do, [s
27d50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 qlite3_step()] w
27d60 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ill automaticall
27d70 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 y recompile the
27d80 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 SQL.** statement
27d90 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 and try to run
27da0 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e it again. As man
27db0 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 y as [SQLITE_MAX
27dc0 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a _SCHEMA_RETRY].*
27dd0 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f * retries will o
27de0 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 ccur before sqli
27df0 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 te3_step() gives
27e00 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 up and returns
27e10 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c an error..** </l
27e20 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a i>.**.** <li>.**
27e30 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 ^When an error
27e40 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 occurs, [sqlite3
27e50 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 _step()] will re
27e60 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 turn one of the
27e70 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 detailed.** [err
27e80 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 or codes] or [ex
27e90 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
27ea0 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 es]. ^The legac
27eb0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 y behavior was t
27ec0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f hat.** [sqlite3_
27ed0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e step()] would on
27ee0 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 ly return a gene
27ef0 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f ric [SQLITE_ERRO
27f00 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a R] result code.*
27f10 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 * and the applic
27f20 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 ation would have
27f30 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e to make a secon
27f40 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 d call to [sqlit
27f50 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 e3_reset()].** i
27f60 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 n order to find
27f70 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 the underlying c
27f80 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 ause of the prob
27f90 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 lem. With the "v
27fa0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 2" prepare.** in
27fb0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e terfaces, the un
27fc0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 derlying reason
27fd0 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 for the error is
27fe0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 returned immedi
27ff0 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a ately..** </li>.
28000 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 **.** <li>.** ^I
28010 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 f the specific v
28020 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 alue bound to [p
28030 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 arameter | host
28040 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 parameter] in th
28050 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 e .** WHERE clau
28060 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e se might influen
28070 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 ce the choice of
28080 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 query plan for
28090 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 a statement,.**
280a0 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 then the stateme
280b0 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d nt will be autom
280c0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 atically recompi
280d0 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 led, as if there
280e0 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 had been .** a
280f0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f schema change, o
28100 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 n the first [sq
28110 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 lite3_step()] ca
28120 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 ll following any
28130 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 change.** to th
28140 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
28150 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d text | bindings]
28160 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 of that [parame
28170 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 ter]. .** ^The s
28180 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 pecific value of
28190 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 WHERE-clause [p
281a0 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 arameter] might
281b0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a influence the .*
281c0 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 * choice of quer
281d0 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 y plan if the pa
281e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c rameter is the l
281f0 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 eft-hand side of
28200 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 a [LIKE].** or
28210 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 [GLOB] operator
28220 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 or if the parame
28230 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 ter is compared
28240 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f to an indexed co
28250 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 lumn.** and the
28260 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 [SQLITE_ENABLE_S
28270 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 TAT3] compile-ti
28280 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 me option is ena
28290 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a bled..** </li>.*
282a0 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 * </ol>.*/.int s
282b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a qlite3_prepare(.
282c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
282d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
282e0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
282f0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
28300 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
28310 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
28320 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 8 encoded */. i
28330 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
28340 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
28350 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
28360 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
28370 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
28380 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
28390 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
283a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
283b0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
283c0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
283d0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
283e0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e of zSql */.);.in
283f0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
28400 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 e_v2(. sqlite3
28410 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
28420 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
28430 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
28440 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 ar *zSql,
28450 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
28460 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 , UTF-8 encoded
28470 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
28480 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
28490 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
284a0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
284b0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
284c0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
284d0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
284e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
284f0 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 t char **pzTail
28500 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
28510 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
28520 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
28530 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
28540 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c prepare16(. sql
28550 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
28560 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
28570 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
28580 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 st void *zSql,
28590 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
285a0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e ement, UTF-16 en
285b0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
285c0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
285d0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
285e0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
285f0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
28600 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
28610 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
28620 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
28630 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 const void **p
28640 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
28650 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
28660 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
28670 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 Sql */.);.int sq
28680 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
28690 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
286a0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
286b0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
286c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
286d0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
286e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
286f0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a UTF-16 encoded *
28700 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
28710 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
28720 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
28730 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
28740 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
28750 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
28760 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
28770 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
28780 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 void **pzTail
28790 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
287a0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
287b0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
287c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
287d0 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 EF: Retrieving S
287e0 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 tatement SQL.**
287f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
28800 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 stmt.**.** ^This
28810 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
28820 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 e used to retrie
28830 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 ve a saved copy
28840 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a of the original.
28850 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 ** SQL text used
28860 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 to create a [pr
28870 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
28880 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d ] if that statem
28890 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 ent was.** compi
288a0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 led using either
288b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
288c0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
288d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
288e0 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ()]..*/.const ch
288f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 ar *sqlite3_sql(
28900 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
28910 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
28920 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 I3REF: Determine
28930 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 If An SQL State
28940 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 ment Writes The
28950 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 Database.** METH
28960 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
28970 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
28980 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
28990 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 y(X) interface r
289a0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e eturns true (non
289b0 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 -zero) if.** and
289c0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 only if the [pr
289d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
289e0 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 ] X makes no dir
289f0 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a ect changes to.*
28a00 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 * the content of
28a10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
28a20 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 le..**.** Note t
28a30 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e hat [application
28a40 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
28a50 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 ctions] or.** [v
28a60 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d irtual tables] m
28a70 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 ight change the
28a80 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 database indirec
28a90 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 tly as a side ef
28aa0 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 fect. .** ^(For
28ab0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 example, if an
28ac0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
28ad0 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 nes a function "
28ae0 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a eval()" that .**
28af0 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f calls [sqlite3_
28b00 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 exec()], then th
28b10 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 e following SQL
28b20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a statement would.
28b30 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 ** change the da
28b40 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f tabase file thro
28b50 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 ugh side-effects
28b60 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
28b70 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 ote><pre>.**
28b80 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c SELECT eval('DEL
28b90 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 ETE FROM t1') FR
28ba0 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e OM t2;.** </pre>
28bb0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
28bc0 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 .** But because
28bd0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 the [SELECT] sta
28be0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
28bf0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 change the datab
28c00 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 ase file.** dire
28c10 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 ctly, sqlite3_st
28c20 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f mt_readonly() wo
28c30 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e uld still return
28c40 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e true.)^.**.** ^
28c50 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 Transaction cont
28c60 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 rol statements s
28c70 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 uch as [BEGIN],
28c80 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 [COMMIT], [ROLLB
28c90 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f ACK],.** [SAVEPO
28ca0 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 INT], and [RELEA
28cb0 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 SE] cause sqlite
28cc0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
28cd0 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 ) to return true
28ce0 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 ,.** since the s
28cf0 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 tatements themse
28d00 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 lves do not actu
28d10 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 ally modify the
28d20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 database but.**
28d30 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 rather they cont
28d40 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f rol the timing o
28d50 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 f when other sta
28d60 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 tements modify t
28d70 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e he .** database.
28d80 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 ^The [ATTACH]
28d90 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 and [DETACH] sta
28da0 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 tements also cau
28db0 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 se.** sqlite3_st
28dc0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f mt_readonly() to
28dd0 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e return true sin
28de0 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 ce, while those
28df0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 statements.** ch
28e00 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 ange the configu
28e10 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 ration of a data
28e20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c base connection,
28e30 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b they do not mak
28e40 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f e .** changes to
28e50 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
28e60 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
28e70 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 es on disk..*/.i
28e80 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f nt sqlite3_stmt_
28e90 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 readonly(sqlite3
28ea0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
28eb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
28ec0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 Determine If A P
28ed0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
28ee0 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 t Has Been Reset
28ef0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
28f00 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
28f10 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 The sqlite3_stmt
28f20 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 _busy(S) interfa
28f30 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 ce returns true
28f40 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 (non-zero) if th
28f50 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
28f60 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 tatement] S has
28f70 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 been stepped at
28f80 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 least once using
28f90 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 .** [sqlite3_st
28fa0 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e ep(S)] but has n
28fb0 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f either run to co
28fc0 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e mpletion (return
28fd0 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f ed.** [SQLITE_DO
28fe0 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 NE] from [sqlite
28ff0 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 3_step(S)]) nor.
29000 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 ** been reset us
29010 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
29020 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 et(S)]. ^The sq
29030 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 lite3_stmt_busy(
29040 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 S).** interface
29050 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 returns false if
29060 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 S is a NULL poi
29070 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e nter. If S is n
29080 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f ot a .** NULL po
29090 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 inter and is not
290a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
290b0 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 valid [prepared
290c0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 statement].** ob
290d0 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 ject, then the b
290e0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
290f0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c ined and probabl
29100 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a y undesirable..*
29110 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
29120 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
29130 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b in combination [
29140 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d sqlite3_next_stm
29150 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 t()].** to locat
29160 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 e all prepared s
29170 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 tatements associ
29180 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 ated with a data
29190 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 base .** connect
291a0 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 ion that are in
291b0 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 need of being re
291c0 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 set. This can b
291d0 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 e used,.** for e
291e0 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e xample, in diagn
291f0 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 ostic routines t
29200 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 o search for pre
29210 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d pared .** statem
29220 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f ents that are ho
29230 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 lding a transact
29240 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 ion open..*/.int
29250 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 sqlite3_stmt_bu
29260 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a sy(sqlite3_stmt*
29270 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
29280 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 EF: Dynamically
29290 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 Typed Value Obje
292a0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ct.** KEYWORDS:
292b0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 {protected sqlit
292c0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f e3_value} {unpro
292d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
292e0 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 alue}.**.** SQLi
292f0 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 te uses the sqli
29300 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
29310 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c to represent al
29320 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 l values.** that
29330 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 can be stored i
29340 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 n a database tab
29350 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 le. SQLite uses
29360 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a dynamic typing.*
29370 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 * for the values
29380 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 it stores. ^Va
29390 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 lues stored in s
293a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
293b0 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 ects.** can be i
293c0 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e ntegers, floatin
293d0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 g point values,
293e0 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 strings, BLOBs,
293f0 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 or NULL..**.** A
29400 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 n sqlite3_value
29410 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 object may be ei
29420 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 ther "protected"
29430 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 or "unprotected
29440 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 "..** Some inter
29450 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 faces require a
29460 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
29470 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 3_value. Other
29480 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 interfaces.** wi
29490 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 ll accept either
294a0 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 a protected or
294b0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 an unprotected s
294c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a qlite3_value..**
294d0 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 Every interface
294e0 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 that accepts sq
294f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 lite3_value argu
29500 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a ments specifies.
29510 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f ** whether or no
29520 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 t it requires a
29530 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
29540 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 3_value. The.**
29550 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
29560 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 dup()] interface
29570 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
29580 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 construct a new
29590 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 .** protected sq
295a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d lite3_value from
295b0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 an unprotected
295c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a sqlite3_value..*
295d0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 *.** The terms "
295e0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 protected" and "
295f0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 unprotected" ref
29600 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 er to whether or
29610 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 not.** a mutex
29620 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 is held. An int
29630 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 ernal mutex is h
29640 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 eld for a protec
29650 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
29660 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 alue object but
29670 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 no mutex is held
29680 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 for an unprotec
29690 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
296a0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 alue object. If
296b0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
296c0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 led to be single
296d0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 -threaded.** (wi
296e0 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 th [SQLITE_THREA
296f0 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 DSAFE=0] and wit
29700 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 h [sqlite3_threa
29710 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 dsafe()] returni
29720 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 ng 0).** or if S
29730 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 QLite is run in
29740 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d one of reduced m
29750 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b utex modes .** [
29760 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
29770 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b NGLETHREAD] or [
29780 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
29790 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 LTITHREAD].** th
297a0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 en there is no d
297b0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 istinction betwe
297c0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 en protected and
297d0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
297e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
297f0 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 jects and they c
29800 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 an be used inter
29810 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 changeably. How
29820 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 ever,.** for max
29830 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 imum code portab
29840 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f ility it is reco
29850 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 mmended that app
29860 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 lications.** sti
29870 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 ll make the dist
29880 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 inction between
29890 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e protected and un
298a0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
298b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
298c0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 ts even when not
298d0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 strictly requir
298e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
298f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
29900 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 ects that are pa
29910 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 ssed as paramete
29920 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 rs into the.** i
29930 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
29940 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 [application-de
29950 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
29960 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 ons] are protect
29970 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 ed..** ^The sqli
29980 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
29990 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
299a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
299b0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 value()] is unpr
299c0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 otected..** Unpr
299d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
299e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 value objects ma
299f0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 y only be used w
29a00 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ith.** [sqlite3_
29a10 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 result_value()]
29a20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e and [sqlite3_bin
29a30 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 d_value()]..** T
29a40 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
29a50 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 e_blob | sqlite3
29a60 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 _value_type()] f
29a70 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 amily of.** inte
29a80 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 rfaces require p
29a90 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
29aa0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a _value objects..
29ab0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
29ac0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 t Mem sqlite3_va
29ad0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lue;../*.** CAPI
29ae0 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 3REF: SQL Functi
29af0 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 on Context Objec
29b00 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 t.**.** The cont
29b10 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 ext in which an
29b20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 SQL function exe
29b30 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 cutes is stored
29b40 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 in an.** sqlite3
29b50 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e _context object.
29b60 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 ^A pointer to
29b70 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 an sqlite3_conte
29b80 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 xt object.** is
29b90 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 always first par
29ba0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 ameter to [appli
29bb0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
29bc0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a QL functions]..*
29bd0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
29be0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
29bf0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
29c00 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 ation will pass
29c10 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 this.** pointer
29c20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c through into cal
29c30 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ls to [sqlite3_r
29c40 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 esult_int | sqli
29c50 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a te3_result()],.*
29c60 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 * [sqlite3_aggre
29c70 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c gate_context()],
29c80 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 [sqlite3_user_d
29c90 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ata()],.** [sqli
29ca0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
29cb0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 andle()], [sqlit
29cc0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 e3_get_auxdata()
29cd0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 ],.** and/or [sq
29ce0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
29cf0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 a()]..*/.typedef
29d00 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
29d10 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f context sqlite3_
29d20 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 context;../*.**
29d30 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e CAPI3REF: Bindin
29d40 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 g Values To Prep
29d50 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a ared Statements.
29d60 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f ** KEYWORDS: {ho
29d70 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 st parameter} {h
29d80 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 ost parameters}
29d90 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 {host parameter
29da0 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 name}.** KEYWORD
29db0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 S: {SQL paramete
29dc0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 r} {SQL paramete
29dd0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 rs} {parameter b
29de0 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f inding}.** METHO
29df0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
29e00 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 **.** ^(In the S
29e10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 QL statement tex
29e20 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 t input to [sqli
29e30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
29e40 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e ] and its varian
29e50 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 ts,.** literals
29e60 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 may be replaced
29e70 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d by a [parameter]
29e80 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e that matches on
29e90 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a e of following.*
29ea0 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a * templates:.**.
29eb0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
29ec0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e ?.** <li> ?NNN
29ed0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a .** <li> :VVV.*
29ee0 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 * <li> @VVV.**
29ef0 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f <li> $VVV.** </
29f00 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 ul>.**.** In the
29f10 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 templates above
29f20 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 , NNN represents
29f30 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 an integer lite
29f40 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 ral,.** and VVV
29f50 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c represents an al
29f60 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 phanumeric ident
29f70 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 ifier.)^ ^The v
29f80 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a alues of these.*
29f90 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c * parameters (al
29fa0 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 so called "host
29fb0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 parameter names"
29fc0 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 or "SQL paramet
29fd0 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 ers").** can be
29fe0 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 set using the sq
29ff0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
2a000 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 outines defined
2a010 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 here..**.** ^The
2a020 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
2a030 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 to the sqlite3_b
2a040 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 ind_*() routines
2a050 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 is always.** a
2a060 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
2a070 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 sqlite3_stmt] ob
2a080 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 ject returned fr
2a090 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 om.** [sqlite3_p
2a0a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
2a0b0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a its variants..**
2a0c0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 .** ^The second
2a0d0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
2a0e0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c index of the SQL
2a0f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 parameter to be
2a100 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 set..** ^The le
2a110 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d ftmost SQL param
2a120 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
2a130 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 x of 1. ^When t
2a140 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a he same named.**
2a150 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 SQL parameter i
2a160 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e s used more than
2a170 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e once, second an
2a180 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 d subsequent.**
2a190 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 occurrences have
2a1a0 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 the same index
2a1b0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 as the first occ
2a1c0 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 urrence..** ^The
2a1d0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 index for named
2a1e0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 parameters can
2a1f0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 be looked up usi
2a200 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
2a210 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2a220 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 r_index()] API i
2a230 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 f desired. ^The
2a240 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f index.** for "?
2a250 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 NNN" parameters
2a260 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 is the value of
2a270 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e NNN..** ^The NNN
2a280 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 value must be b
2a290 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 etween 1 and the
2a2a0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
2a2b0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 )].** parameter
2a2c0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 [SQLITE_LIMIT_VA
2a2d0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 RIABLE_NUMBER] (
2a2e0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 default value: 9
2a2f0 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 99)..**.** ^The
2a300 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
2a310 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 s the value to b
2a320 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d ind to the param
2a330 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 eter..** ^If the
2a340 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
2a350 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2a360 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 _text() or sqlit
2a370 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 e3_bind_text16()
2a380 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 .** or sqlite3_b
2a390 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 ind_blob() is a
2a3a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
2a3b0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 n the fourth par
2a3c0 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e ameter.** is ign
2a3d0 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 ored and the end
2a3e0 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 result is the s
2a3f0 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 ame as sqlite3_b
2a400 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a ind_null()..**.*
2a410 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 * ^(In those rou
2a420 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 tines that have
2a430 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e a fourth argumen
2a440 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 t, its value is
2a450 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
2a460 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 bytes in the pa
2a470 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 rameter. To be
2a480 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 clear: the value
2a490 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 is the.** numbe
2a4a0 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 r of <u>bytes</u
2a4b0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 > in the value,
2a4c0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f not the number o
2a4d0 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a f characters.)^.
2a4e0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 ** ^If the fourt
2a4f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
2a500 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2a510 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 () or sqlite3_bi
2a520 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 nd_text16().** i
2a530 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
2a540 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 the length of t
2a550 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 he string is.**
2a560 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
2a570 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 tes up to the fi
2a580 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 rst zero termina
2a590 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 tor..** If the f
2a5a0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
2a5b0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f to sqlite3_bind_
2a5c0 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 blob() is negati
2a5d0 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ve, then.** the
2a5e0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
2a5f0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e fined..** If a n
2a600 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 on-negative four
2a610 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
2a620 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 provided to sqli
2a630 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a te3_bind_text().
2a640 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 ** or sqlite3_bi
2a650 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 nd_text16() or s
2a660 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2a670 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 64() then.** tha
2a680 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 t parameter must
2a690 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 be the byte off
2a6a0 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 set.** where the
2a6b0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 NUL terminator
2a6c0 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 would occur assu
2a6d0 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 ming the string
2a6e0 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d were NUL.** term
2a6f0 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 inated. If any
2a700 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f NUL characters o
2a710 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 ccur at byte off
2a720 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a sets less than .
2a730 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ** the value of
2a740 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
2a750 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 eter then the re
2a760 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 sulting string v
2a770 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e alue will.** con
2a780 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 tain embedded NU
2a790 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 Ls. The result
2a7a0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 of expressions i
2a7b0 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 nvolving strings
2a7c0 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 .** with embedde
2a7d0 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 d NULs is undefi
2a7e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
2a7f0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 fifth argument t
2a800 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 o the BLOB and s
2a810 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e tring binding in
2a820 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 terfaces.** is a
2a830 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 destructor used
2a840 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 to dispose of t
2a850 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 he BLOB or.** st
2a860 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 ring after SQLit
2a870 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 e has finished w
2a880 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 ith it. ^The de
2a890 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c structor is call
2a8a0 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 ed.** to dispose
2a8b0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 of the BLOB or
2a8c0 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 string even if t
2a8d0 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 he call to bind
2a8e0 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 API fails..** ^I
2a8f0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 f the fifth argu
2a900 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 ment is.** the s
2a910 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 pecial value [SQ
2a920 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 LITE_STATIC], th
2a930 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 en SQLite assume
2a940 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e s that the.** in
2a950 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 formation is in
2a960 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 static, unmanage
2a970 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 d space and does
2a980 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 not need to be
2a990 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 freed..** ^If th
2a9a0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
2a9b0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b has the value [
2a9c0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
2a9d0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 ], then.** SQLit
2a9e0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 e makes its own
2a9f0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 private copy of
2aa00 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 the data immedia
2aa10 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 tely, before.**
2aa20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
2aa30 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 _*() routine ret
2aa40 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 urns..**.** ^The
2aa50 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 sixth argument
2aa60 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f to sqlite3_bind_
2aa70 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 text64() must be
2aa80 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 one of.** [SQLI
2aa90 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 TE_UTF8], [SQLIT
2aaa0 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 E_UTF16], [SQLIT
2aab0 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b E_UTF16BE], or [
2aac0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a SQLITE_UTF16LE].
2aad0 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 ** to specify th
2aae0 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 e encoding of th
2aaf0 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 e text in the th
2ab00 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 ird parameter.
2ab10 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 If.** the sixth
2ab20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
2ab30 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 te3_bind_text64(
2ab40 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 ) is not one of
2ab50 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 the.** allowed v
2ab60 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 alues shown abov
2ab70 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 e, or if the tex
2ab80 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 t encoding is di
2ab90 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 fferent.** from
2aba0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 the encoding spe
2abb0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 cified by the si
2abc0 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 xth parameter, t
2abd0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
2abe0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 .** is undefined
2abf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
2ac00 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
2ac10 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e ob() routine bin
2ac20 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e ds a BLOB of len
2ac30 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 gth N that.** is
2ac40 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 filled with zer
2ac50 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f oes. ^A zeroblo
2ac60 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 b uses a fixed a
2ac70 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a mount of memory.
2ac80 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 ** (just an inte
2ac90 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 ger to hold its
2aca0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 size) while it i
2acb0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 s being processe
2acc0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 d..** Zeroblobs
2acd0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 are intended to
2ace0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f serve as placeho
2acf0 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 lders for BLOBs
2ad00 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 whose.** content
2ad10 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 is later writte
2ad20 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 n using.** [sqli
2ad30 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 te3_blob_open |
2ad40 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 incremental BLOB
2ad50 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a I/O] routines..
2ad60 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 ** ^A negative v
2ad70 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 alue for the zer
2ad80 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e oblob results in
2ad90 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 a zero-length B
2ada0 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 LOB..**.** ^If a
2adb0 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ny of the sqlite
2adc0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
2add0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 nes are called w
2ade0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
2adf0 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 er.** for the [p
2ae00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2ae10 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 t] or with a pre
2ae20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
2ae30 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 for which.** [sq
2ae40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 lite3_step()] ha
2ae50 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f s been called mo
2ae60 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e re recently than
2ae70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2ae80 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 )],.** then the
2ae90 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e call will return
2aea0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
2aeb0 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 . If any sqlite
2aec0 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 3_bind_().** rou
2aed0 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 tine is passed a
2aee0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2aef0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 ment] that has b
2af00 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 een finalized, t
2af10 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 he.** result is
2af20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 undefined and pr
2af30 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a obably harmful..
2af40 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 **.** ^Bindings
2af50 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 are not cleared
2af60 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
2af70 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 reset()] routine
2af80 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 ..** ^Unbound pa
2af90 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 rameters are int
2afa0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c erpreted as NULL
2afb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
2afc0 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 ite3_bind_* rout
2afd0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c ines return [SQL
2afe0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
2aff0 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 ss or an.** [err
2b000 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 or code] if anyt
2b010 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e hing goes wrong.
2b020 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f .** ^[SQLITE_TOO
2b030 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 BIG] might be re
2b040 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 turned if the si
2b050 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f ze of a string o
2b060 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 r BLOB.** exceed
2b070 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 s limits imposed
2b080 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d by [sqlite3_lim
2b090 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 it]([SQLITE_LIMI
2b0a0 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a T_LENGTH]) or.**
2b0b0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e [SQLITE_MAX_LEN
2b0c0 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 GTH]..** ^[SQLIT
2b0d0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 E_RANGE] is retu
2b0e0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 rned if the para
2b0f0 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 meter.** index i
2b100 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 s out of range.
2b110 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d ^[SQLITE_NOMEM]
2b120 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
2b130 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a malloc() fails..
2b140 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
2b150 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2b160 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
2b170 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
2b180 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
2b190 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 e()], and [sqlit
2b1a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2b1b0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 r_index()]..*/.i
2b1c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2b1d0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d blob(sqlite3_stm
2b1e0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 t*, int, const v
2b1f0 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 oid*, int n, voi
2b200 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e d(*)(void*));.in
2b210 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 t sqlite3_bind_b
2b220 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 lob64(sqlite3_st
2b230 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
2b240 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 void*, sqlite3_u
2b250 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 int64,.
2b260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
2b270 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
2b280 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2b290 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
2b2a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 stmt*, int, doub
2b2b0 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 le);.int sqlite3
2b2c0 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 _bind_int(sqlite
2b2d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 3_stmt*, int, in
2b2e0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f t);.int sqlite3_
2b2f0 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 bind_int64(sqlit
2b300 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 e3_stmt*, int, s
2b310 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 qlite3_int64);.i
2b320 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2b330 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d null(sqlite3_stm
2b340 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 t*, int);.int sq
2b350 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
2b360 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2b370 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e t,const char*,in
2b380 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 t,void(*)(void*)
2b390 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
2b3a0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 ind_text16(sqlit
2b3b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
2b3c0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
2b3d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
2b3e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
2b3f0 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 nd_text64(sqlite
2b400 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
2b410 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 nst char*, sqlit
2b420 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 e3_uint64,.
2b430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2b440 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 void(*)(void
2b450 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 *), unsigned cha
2b460 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 r encoding);.int
2b470 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 sqlite3_bind_va
2b480 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lue(sqlite3_stmt
2b490 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 *, int, const sq
2b4a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
2b4b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2b4c0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
2b4d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
2b4e0 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 n);.int sqlite3
2b4f0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 _bind_zeroblob64
2b500 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2b510 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e int, sqlite3_uin
2b520 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 t64);../*.** CAP
2b530 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 I3REF: Number Of
2b540 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a SQL Parameters.
2b550 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2b560 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
2b570 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 his routine can
2b580 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 be used to find
2b590 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 the number of [S
2b5a0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a QL parameters].*
2b5b0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 * in a [prepared
2b5c0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 statement]. SQ
2b5d0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 L parameters are
2b5e0 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a tokens of the.*
2b5f0 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e * form "?", "?NN
2b600 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 N", ":AAA", "$AA
2b610 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 A", or "@AAA" th
2b620 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 at serve as.** p
2b630 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 laceholders for
2b640 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 values that are
2b650 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2b660 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 ob | bound].** t
2b670 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 o the parameters
2b680 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 at a later time
2b690 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 ..**.** ^(This r
2b6a0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 outine actually
2b6b0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 returns the inde
2b6c0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 x of the largest
2b6d0 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 (rightmost).**
2b6e0 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 parameter. For a
2b6f0 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 ll forms except
2b700 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 ?NNN, this will
2b710 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 correspond to th
2b720 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 e.** number of u
2b730 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 nique parameters
2b740 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 . If parameters
2b750 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 of the ?NNN for
2b760 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 m are used,.** t
2b770 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 here may be gaps
2b780 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a in the list.)^.
2b790 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
2b7a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2b7b0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
2b7c0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
2b7d0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
2b7e0 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b ame()], and.** [
2b7f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2b800 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
2b810 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2b820 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
2b830 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
2b840 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2b850 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 3REF: Name Of A
2b860 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a Host Parameter.*
2b870 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
2b880 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
2b890 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 e sqlite3_bind_p
2b8a0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c arameter_name(P,
2b8b0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 N) interface ret
2b8c0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 urns.** the name
2b8d0 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 of the N-th [SQ
2b8e0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 L parameter] in
2b8f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
2b900 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e atement] P..** ^
2b910 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 (SQL parameters
2b920 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e of the form "?NN
2b930 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 N" or ":AAA" or
2b940 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 "@AAA" or "$AAA"
2b950 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 .** have a name
2b960 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 which is the str
2b970 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a ing "?NNN" or ":
2b980 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f AAA" or "@AAA" o
2b990 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 r "$AAA".** resp
2b9a0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 ectively..** In
2b9b0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
2b9c0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 initial ":" or
2b9d0 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f "$" or "@" or "?
2b9e0 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 ".** is included
2b9f0 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 as part of the
2ba00 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 name.)^.** ^Para
2ba10 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f meters of the fo
2ba20 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 rm "?" without a
2ba30 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 following integ
2ba40 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a er have no name.
2ba50 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 ** and are refer
2ba60 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c red to as "namel
2ba70 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f ess" or "anonymo
2ba80 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a us parameters"..
2ba90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
2baa0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 host parameter
2bab0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 has an index of
2bac0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 1, not 0..**.**
2bad0 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 ^If the value N
2bae0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 is out of range
2baf0 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 or if the N-th p
2bb00 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e arameter is.** n
2bb10 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 ameless, then NU
2bb20 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 LL is returned.
2bb30 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
2bb40 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 tring is.** alwa
2bb50 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f ys in UTF-8 enco
2bb60 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 ding even if the
2bb70 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 named parameter
2bb80 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c was.** original
2bb90 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 ly specified as
2bba0 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 UTF-16 in [sqlit
2bbb0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
2bbc0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 or.** [sqlite3_p
2bbd0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
2bbe0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
2bbf0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2bc00 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
2bc10 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
2bc20 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
2bc30 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 ount()], and.**
2bc40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2bc50 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
2bc60 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ..*/.const char
2bc70 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 *sqlite3_bind_pa
2bc80 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c rameter_name(sql
2bc90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 ite3_stmt*, int)
2bca0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2bcb0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 F: Index Of A Pa
2bcc0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 rameter With A G
2bcd0 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 iven Name.** MET
2bce0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
2bcf0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 t.**.** ^Return
2bd00 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 the index of an
2bd10 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 SQL parameter gi
2bd20 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e ven its name. ^
2bd30 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c The.** index val
2bd40 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 ue returned is s
2bd50 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 uitable for use
2bd60 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a as the second.**
2bd70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
2bd80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2bd90 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
2bda0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 . ^A zero.** is
2bdb0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 returned if no
2bdc0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 matching paramet
2bdd0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 er is found. ^T
2bde0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
2bdf0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 name must be giv
2be00 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e en in UTF-8 even
2be10 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c if the original
2be20 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 statement.** wa
2be30 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 s prepared from
2be40 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e UTF-16 text usin
2be50 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
2be60 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a re16_v2()]..**.*
2be70 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
2be80 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
2be90 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
2bea0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
2beb0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
2bec0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
2bed0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2bee0 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a ter_name()]..*/.
2bef0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2bf00 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
2bf10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2bf20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
2bf30 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 e);../*.** CAPI3
2bf40 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 REF: Reset All B
2bf50 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 indings On A Pre
2bf60 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a pared Statement.
2bf70 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2bf80 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 e3_stmt.**.** ^C
2bf90 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 ontrary to the i
2bfa0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 ntuition of many
2bfb0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 , [sqlite3_reset
2bfc0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 ()] does not res
2bfd0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 et.** the [sqlit
2bfe0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
2bff0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 indings] on a [p
2c000 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2c010 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 t]..** ^Use this
2c020 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 routine to rese
2c030 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d t all host param
2c040 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a eters to NULL..*
2c050 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c /.int sqlite3_cl
2c060 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c ear_bindings(sql
2c070 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
2c080 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
2c090 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 mber Of Columns
2c0a0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a In A Result Set.
2c0b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2c0c0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 e3_stmt.**.** ^R
2c0d0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 eturn the number
2c0e0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
2c0f0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 he result set re
2c100 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a turned by the.**
2c110 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2c120 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 ment]. ^This rou
2c130 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 tine returns 0 i
2c140 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 f pStmt is an SQ
2c150 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 L.** statement t
2c160 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 hat does not ret
2c170 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 urn data (for ex
2c180 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 ample an [UPDATE
2c190 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ])..**.** See al
2c1a0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 so: [sqlite3_dat
2c1b0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e a_count()].*/.in
2c1c0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
2c1d0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
2c1e0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
2c1f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
2c200 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 lumn Names In A
2c210 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 Result Set.** ME
2c220 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2c230 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 mt.**.** ^These
2c240 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
2c250 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 the name assigne
2c260 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 d to a particula
2c270 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 r column.** in t
2c280 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 he result set of
2c290 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 a [SELECT] stat
2c2a0 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c ement. ^The sql
2c2b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
2c2c0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
2c2d0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
2c2e0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
2c2f0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
2c300 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 ing.** and sqlit
2c310 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
2c320 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 () returns a poi
2c330 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 nter to a zero-t
2c340 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
2c350 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 -16 string. ^Th
2c360 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
2c370 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 r is the [prepar
2c380 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
2c390 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 that implements
2c3a0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 the [SELECT] st
2c3b0 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 atement. ^The se
2c3c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
2c3d0 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 s the.** column
2c3e0 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 number. ^The le
2c3f0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 ftmost column is
2c400 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a number 0..**.**
2c410 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
2c420 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 tring pointer is
2c430 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 valid until eit
2c440 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 her the [prepare
2c450 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
2c460 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 is destroyed by
2c470 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2c480 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 e()] or until th
2c490 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
2c4a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 utomatically.**
2c4b0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 reprepared by th
2c4c0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 e first call to
2c4d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2c4e0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
2c4f0 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 r run.** or unti
2c500 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 l the next call
2c510 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f to.** sqlite3_co
2c520 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 lumn_name() or s
2c530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
2c540 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 me16() on the sa
2c550 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a me column..**.**
2c560 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^If sqlite3_mal
2c570 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 loc() fails duri
2c580 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e ng the processin
2c590 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 g of either rout
2c5a0 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d ine.** (for exam
2c5b0 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e ple during a con
2c5c0 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 version from UTF
2c5d0 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 -8 to UTF-16) th
2c5e0 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 en a.** NULL poi
2c5f0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 nter is returned
2c600 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d ..**.** ^The nam
2c610 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f e of a result co
2c620 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 lumn is the valu
2c630 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c e of the "AS" cl
2c640 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 ause for.** that
2c650 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 column, if ther
2c660 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 e is an AS claus
2c670 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 e. If there is
2c680 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 no AS clause.**
2c690 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 then the name of
2c6a0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 the column is u
2c6b0 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d nspecified and m
2c6c0 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a ay change from.*
2c6d0 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 * one release of
2c6e0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e SQLite to the n
2c6f0 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ext..*/.const ch
2c700 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
2c710 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f mn_name(sqlite3_
2c720 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 stmt*, int N);.c
2c730 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
2c740 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
2c750 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2c760 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int N);../*.** C
2c770 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 API3REF: Source
2c780 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 Of Data In A Que
2c790 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 ry Result.** MET
2c7a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
2c7b0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 t.**.** ^These r
2c7c0 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 outines provide
2c7d0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 a means to deter
2c7e0 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 mine the databas
2c7f0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a e, table, and.**
2c800 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 table column th
2c810 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e at is the origin
2c820 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 of a particular
2c830 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 result column i
2c840 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 n.** [SELECT] st
2c850 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 atement..** ^The
2c860 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
2c870 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f abase or table o
2c880 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 r column can be
2c890 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 returned as.** e
2c8a0 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 ither a UTF-8 or
2c8b0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 UTF-16 string.
2c8c0 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f ^The _database_
2c8d0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2c8e0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
2c8f0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c name, the _tabl
2c900 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 e_ routines retu
2c910 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d rn the table nam
2c920 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 e, and.** the or
2c930 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 igin_ routines r
2c940 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e eturn the column
2c950 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 name..** ^The r
2c960 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
2c970 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 s valid until th
2c980 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2c990 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f ement] is destro
2c9a0 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 yed.** using [sq
2c9b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2c9c0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 ] or until the s
2c9d0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f tatement is auto
2c9e0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 matically.** rep
2c9f0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 repared by the f
2ca00 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 irst call to [sq
2ca10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f lite3_step()] fo
2ca20 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 r a particular r
2ca30 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 un.** or until t
2ca40 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 he same informat
2ca50 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 ion is requested
2ca60 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 .** again in a d
2ca70 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e ifferent encodin
2ca80 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 g..**.** ^The na
2ca90 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 mes returned are
2caa0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e the original un
2cab0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f -aliased names o
2cac0 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 f the.** databas
2cad0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f e, table, and co
2cae0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 lumn..**.** ^The
2caf0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
2cb00 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 to these interfa
2cb10 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 ces is a [prepar
2cb20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
2cb30 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f * ^These functio
2cb40 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d ns return inform
2cb50 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 ation about the
2cb60 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d Nth result colum
2cb70 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a n returned by.**
2cb80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 the statement,
2cb90 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 where N is the s
2cba0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 econd function a
2cbb0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 rgument..** ^The
2cbc0 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d left-most colum
2cbd0 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f n is column 0 fo
2cbe0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 r these routines
2cbf0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
2cc00 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 Nth column retur
2cc10 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 ned by the state
2cc20 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 ment is an expre
2cc30 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 ssion or.** subq
2cc40 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 uery and is not
2cc50 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 a column value,
2cc60 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 then all of thes
2cc70 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
2cc80 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 rn.** NULL. ^Th
2cc90 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 ese routine migh
2cca0 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 t also return NU
2ccb0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 LL if a memory a
2ccc0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a llocation error.
2ccd0 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 ** occurs. ^Oth
2cce0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 erwise, they ret
2ccf0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 urn the name of
2cd00 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 the attached dat
2cd10 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a abase, table,.**
2cd20 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 or column that
2cd30 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c query result col
2cd40 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 umn was extracte
2cd50 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 d from..**.** ^A
2cd60 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 s with all other
2cd70 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 SQLite APIs, th
2cd80 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 ose whose names
2cd90 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 end with "16" re
2cda0 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 turn.** UTF-16 e
2cdb0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 ncoded strings a
2cdc0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e nd the other fun
2cdd0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 ctions return UT
2cde0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 F-8..**.** ^Thes
2cdf0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 e APIs are only
2ce00 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 available if the
2ce10 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d library was com
2ce20 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
2ce30 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 * [SQLITE_ENABLE
2ce40 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 _COLUMN_METADATA
2ce50 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C-preprocessor
2ce60 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 symbol..**.** I
2ce70 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 f two or more th
2ce80 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f reads call one o
2ce90 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 r more of these
2cea0 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 routines against
2ceb0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 the same.** pre
2cec0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
2ced0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 and column at th
2cee0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e e same time then
2cef0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
2cf00 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a .** undefined..*
2cf10 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d *.** If two or m
2cf20 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c ore threads call
2cf30 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
2cf40 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2cf50 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 database_name |
2cf60 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 column metadata
2cf70 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 interfaces].** f
2cf80 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 or the same [pre
2cf90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2cfa0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 and result colu
2cfb0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d mn.** at the sam
2cfc0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 e time then the
2cfd0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
2cfe0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 fined..*/.const
2cff0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
2d000 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
2d010 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
2d020 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
2d030 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
2d040 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 n_database_name1
2d050 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
2d060 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 int);.const char
2d070 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
2d080 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 _table_name(sqli
2d090 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
2d0a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
2d0b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 te3_column_table
2d0c0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
2d0d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
2d0e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
2d0f0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
2d100 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
2d110 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
2d120 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
2d130 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 n_origin_name16(
2d140 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2d150 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2d160 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 REF: Declared Da
2d170 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 tatype Of A Quer
2d180 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 y Result.** METH
2d190 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2d1a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 .**.** ^(The fir
2d1b0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
2d1c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2d1d0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 ement]..** If th
2d1e0 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 is statement is
2d1f0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 a [SELECT] state
2d200 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 ment and the Nth
2d210 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a column of the.*
2d220 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c * returned resul
2d230 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 t set of that [S
2d240 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c ELECT] is a tabl
2d250 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e e column (not an
2d260 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f .** expression o
2d270 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e r subquery) then
2d280 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 the declared ty
2d290 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a pe of the table.
2d2a0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 ** column is ret
2d2b0 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 urned.)^ ^If th
2d2c0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 e Nth column of
2d2d0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 the result set i
2d2e0 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 s an.** expressi
2d2f0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 on or subquery,
2d300 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e then a NULL poin
2d310 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ter is returned.
2d320 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 .** ^The returne
2d330 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 d string is alwa
2d340 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 ys UTF-8 encoded
2d350 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 ..**.** ^(For ex
2d360 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 ample, given the
2d370 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 database schema
2d380 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 :.**.** CREATE T
2d390 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 ABLE t1(c1 VARIA
2d3a0 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 NT);.**.** and t
2d3b0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 he following sta
2d3c0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d tement to be com
2d3d0 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c piled:.**.** SEL
2d3e0 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 ECT c1 + 1, c1 F
2d3f0 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 ROM t1;.**.** th
2d400 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 is routine would
2d410 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 return the stri
2d420 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 ng "VARIANT" for
2d430 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 the second resu
2d440 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d lt.** column (i=
2d450 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 =1), and a NULL
2d460 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 pointer for the
2d470 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c first result col
2d480 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a umn (i==0).)^.**
2d490 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 .** ^SQLite uses
2d4a0 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d dynamic run-tim
2d4b0 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a e typing. ^So j
2d4c0 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f ust because a co
2d4d0 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 lumn.** is decla
2d4e0 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 red to contain a
2d4f0 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 particular type
2d500 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 does not mean t
2d510 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 hat the.** data
2d520 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 stored in that c
2d530 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 olumn is of the
2d540 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 declared type.
2d550 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 SQLite is.** str
2d560 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 ongly typed, but
2d570 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 the typing is d
2d580 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 ynamic not stati
2d590 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 c. ^Type.** is
2d5a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
2d5b0 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 individual value
2d5c0 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 s, not with the
2d5d0 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 containers.** us
2d5e0 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 ed to hold those
2d5f0 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 values..*/.cons
2d600 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
2d610 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 column_decltype(
2d620 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2d630 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a t);.const void *
2d640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
2d650 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 ecltype16(sqlite
2d660 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 3_stmt*,int);../
2d670 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
2d680 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 valuate An SQL S
2d690 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 tatement.** METH
2d6a0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2d6b0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b .**.** After a [
2d6c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2d6d0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 nt] has been pre
2d6e0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 pared using eith
2d6f0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 er.** [sqlite3_p
2d700 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
2d710 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2d720 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 16_v2()] or one
2d730 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a of the legacy.**
2d740 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c interfaces [sql
2d750 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
2d760 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
2d770 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 are16()], this f
2d780 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 unction.** must
2d790 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 be called one or
2d7a0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 more times to e
2d7b0 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 valuate the stat
2d7c0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ement..**.** The
2d7d0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 details of the
2d7e0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 behavior of the
2d7f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
2d800 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a nterface depend.
2d810 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 ** on whether th
2d820 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 e statement was
2d830 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 prepared using t
2d840 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e he newer "v2" in
2d850 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 terface.** [sqli
2d860 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2d870 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
2d880 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f repare16_v2()] o
2d890 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 r the older lega
2d8a0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 cy.** interface
2d8b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2d8c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2d8d0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 _prepare16()].
2d8e0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a The use of the.*
2d8f0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 * new "v2" inter
2d900 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
2d910 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c ded for new appl
2d920 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 ications but the
2d930 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 legacy.** inter
2d940 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e face will contin
2d950 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ue to be support
2d960 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 ed..**.** ^In th
2d970 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 e legacy interfa
2d980 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 ce, the return v
2d990 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 alue will be eit
2d9a0 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 her [SQLITE_BUSY
2d9b0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f ],.** [SQLITE_DO
2d9c0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 NE], [SQLITE_ROW
2d9d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ], [SQLITE_ERROR
2d9e0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 ], or [SQLITE_MI
2d9f0 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 SUSE]..** ^With
2da00 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2da10 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f ce, any of the o
2da20 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 ther [result cod
2da30 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e es] or.** [exten
2da40 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
2da50 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 ] might be retur
2da60 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a ned as well..**.
2da70 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 ** ^[SQLITE_BUSY
2da80 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
2da90 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 database engine
2daa0 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 was unable to a
2dab0 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 cquire the.** da
2dac0 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 tabase locks it
2dad0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 needs to do its
2dae0 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 job. ^If the st
2daf0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f atement is a [CO
2db00 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 MMIT].** or occu
2db10 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e rs outside of an
2db20 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
2db30 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 ction, then you
2db40 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a can retry the.**
2db50 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 statement. If
2db60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
2db70 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 not a [COMMIT]
2db80 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 and occurs withi
2db90 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 n an.** explicit
2dba0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 transaction the
2dbb0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c n you should rol
2dbc0 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 lback the transa
2dbd0 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 ction before.**
2dbe0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a continuing..**.*
2dbf0 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d * ^[SQLITE_DONE]
2dc00 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
2dc10 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 statement has fi
2dc20 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 nished executing
2dc30 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 .** successfully
2dc40 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 . sqlite3_step(
2dc50 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ) should not be
2dc60 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 called again on
2dc70 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 this virtual.**
2dc80 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 machine without
2dc90 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 first calling [s
2dca0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2dcb0 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 to reset the vir
2dcc0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 tual.** machine
2dcd0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 back to its init
2dce0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a ial state..**.**
2dcf0 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 ^If the SQL sta
2dd00 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 tement being exe
2dd10 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e cuted returns an
2dd20 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 y data, then [SQ
2dd30 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 LITE_ROW].** is
2dd40 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 returned each ti
2dd50 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 me a new row of
2dd60 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f data is ready fo
2dd70 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 r processing by
2dd80 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 the.** caller. T
2dd90 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 he values may be
2dda0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 accessed using
2ddb0 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 the [column acce
2ddc0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a ss functions]..*
2ddd0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
2dde0 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e is called again
2ddf0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 to retrieve the
2de00 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 next row of dat
2de10 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 a..**.** ^[SQLIT
2de20 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 E_ERROR] means t
2de30 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 hat a run-time e
2de40 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 rror (such as a
2de50 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 constraint.** vi
2de60 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 olation) has occ
2de70 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f urred. sqlite3_
2de80 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f step() should no
2de90 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 t be called agai
2dea0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 n on.** the VM.
2deb0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e More information
2dec0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 may be found by
2ded0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
2dee0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 3_errmsg()]..**
2def0 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 ^With the legacy
2df00 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f interface, a mo
2df10 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f re specific erro
2df20 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d r code (for exam
2df30 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ple,.** [SQLITE_
2df40 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c INTERRUPT], [SQL
2df50 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 ITE_SCHEMA], [SQ
2df60 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 LITE_CORRUPT], a
2df70 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 nd so forth).**
2df80 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 can be obtained
2df90 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
2dfa0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 te3_reset()] on
2dfb0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
2dfc0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 statement]. ^I
2dfd0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 n the "v2" inter
2dfe0 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 face,.** the mor
2dff0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 e specific error
2e000 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 code is returne
2e010 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 d directly by sq
2e020 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a lite3_step()..**
2e030 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 .** [SQLITE_MISU
2e040 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 SE] means that t
2e050 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 he this routine
2e060 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 was called inapp
2e070 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 ropriately..** P
2e080 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 erhaps it was ca
2e090 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 lled on a [prepa
2e0a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
2e0b0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 hat has.** alrea
2e0c0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 dy been [sqlite3
2e0d0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 _finalize | fina
2e0e0 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 lized] or on one
2e0f0 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 that had.** pre
2e100 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 viously returned
2e110 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
2e120 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d or [SQLITE_DONE]
2e130 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a . Or it could.*
2e140 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 * be the case th
2e150 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 at the same data
2e160 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2e170 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 is being used by
2e180 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 two or.** more
2e190 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 threads at the s
2e1a0 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 ame moment in ti
2e1b0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c me..**.** For al
2e1c0 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 l versions of SQ
2e1d0 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 Lite up to and i
2e1e0 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e ncluding 3.6.23.
2e1f0 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 1, a call to.**
2e200 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2e210 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 ] was required a
2e220 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 fter sqlite3_ste
2e230 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 p() returned any
2e240 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 thing.** other t
2e250 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d han [SQLITE_ROW]
2e260 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 before any subs
2e270 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f equent invocatio
2e280 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f n of.** sqlite3_
2e290 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 step(). Failure
2e2a0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 to reset the pr
2e2b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2e2c0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 using .** [sqli
2e2d0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 te3_reset()] wou
2e2e0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 ld result in an
2e2f0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
2e300 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 return from.** s
2e310 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
2e320 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f But after versio
2e330 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 n 3.6.23.1, sqli
2e340 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e te3_step() began
2e350 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c .** calling [sql
2e360 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 ite3_reset()] au
2e370 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 tomatically in t
2e380 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 his circumstance
2e390 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 rather.** than
2e3a0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 returning [SQLIT
2e3b0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 E_MISUSE]. This
2e3c0 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 is not consider
2e3d0 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 ed a compatibili
2e3e0 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 ty.** break beca
2e3f0 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 use any applicat
2e400 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 ion that ever re
2e410 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 ceives an SQLITE
2e420 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a _MISUSE error.**
2e430 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 is broken by de
2e440 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b finition. The [
2e450 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
2e460 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 RESET] compile-t
2e470 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 ime option.** ca
2e480 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 n be used to res
2e490 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 tore the legacy
2e4a0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 behavior..**.**
2e4b0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 <b>Goofy Interfa
2e4c0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e ce Alert:</b> In
2e4d0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
2e4e0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 rface, the sqlit
2e4f0 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 e3_step().** API
2e500 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
2e510 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 a generic error
2e520 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 code, [SQLITE_ER
2e530 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 ROR], following
2e540 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 any.** error oth
2e550 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
2e560 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 BUSY] and [SQLIT
2e570 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 E_MISUSE]. You
2e580 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 must call.** [sq
2e590 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
2e5a0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
2e5b0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 ize()] in order
2e5c0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 to find one of t
2e5d0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b he.** specific [
2e5e0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 error codes] tha
2e5f0 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 t better describ
2e600 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a es the error..**
2e610 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 We admit that t
2e620 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 his is a goofy d
2e630 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 esign. The prob
2e640 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 lem has been fix
2e650 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 ed.** with the "
2e660 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 v2" interface.
2e670 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 If you prepare a
2e680 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 ll of your SQL s
2e690 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 tatements.** usi
2e6a0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 ng either [sqlit
2e6b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2e6c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
2e6d0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 pare16_v2()] ins
2e6e0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c tead.** of the l
2e6f0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 egacy [sqlite3_p
2e700 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 repare()] and [s
2e710 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2e720 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a ()] interfaces,.
2e730 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 ** then the more
2e740 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
2e750 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 codes] are retu
2e760 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a rned directly.**
2e770 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
2e780 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 (). The use of
2e790 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2e7a0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
2e7b0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
2e7c0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 3_step(sqlite3_s
2e7d0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
2e7e0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f PI3REF: Number o
2e7f0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 f columns in a r
2e800 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 esult set.** MET
2e810 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
2e820 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c t.**.** ^The sql
2e830 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
2e840 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 P) interface ret
2e850 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
2e860 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
2e870 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 e.** current row
2e880 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
2e890 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 et of [prepared
2e8a0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a statement] P..**
2e8b0 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 ^If prepared st
2e8c0 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e atement P does n
2e8d0 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 ot have results
2e8e0 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a ready to return.
2e8f0 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f ** (via calls to
2e900 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
2e910 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 lumn_int | sqlit
2e920 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f e3_column_*()] o
2e930 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 f.** interfaces)
2e940 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 then sqlite3_da
2e950 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 ta_count(P) retu
2e960 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 rns 0..** ^The s
2e970 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2e980 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 t(P) routine als
2e990 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 o returns 0 if P
2e9a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
2e9b0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 er..** ^The sqli
2e9c0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
2e9d0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
2e9e0 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 s 0 if the previ
2e9f0 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ous call to.** [
2ea00 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 sqlite3_step](P)
2ea10 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
2ea20 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 E_DONE]. ^The s
2ea30 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2ea40 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 t(P).** will ret
2ea50 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 urn non-zero if
2ea60 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
2ea70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 [sqlite3_step](
2ea80 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b P) returned.** [
2ea90 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 SQLITE_ROW], exc
2eaa0 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 ept in the case
2eab0 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 of the [PRAGMA i
2eac0 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 ncremental_vacuu
2ead0 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 m].** where it a
2eae0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 lways returns ze
2eaf0 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 ro since each st
2eb00 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 ep of that multi
2eb10 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 -step.** pragma
2eb20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e returns 0 column
2eb30 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a s of data..**.**
2eb40 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
2eb50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 te3_column_count
2eb60 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ()].*/.int sqlit
2eb70 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 e3_data_count(sq
2eb80 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
2eb90 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2eba0 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c REF: Fundamental
2ebb0 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 Datatypes.** KE
2ebc0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 YWORDS: SQLITE_T
2ebd0 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 EXT.**.** ^(Ever
2ebe0 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 y value in SQLit
2ebf0 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 e has one of fiv
2ec00 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 e fundamental da
2ec10 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c tatypes:.**.** <
2ec20 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 ul>.** <li> 64-b
2ec30 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
2ec40 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 r.** <li> 64-bit
2ec50 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 IEEE floating p
2ec60 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c oint number.** <
2ec70 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c li> string.** <l
2ec80 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 i> BLOB.** <li>
2ec90 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a NULL.** </ul>)^.
2eca0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
2ecb0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 tants are codes
2ecc0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 for each of thos
2ecd0 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e e types..**.** N
2ece0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c ote that the SQL
2ecf0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e ITE_TEXT constan
2ed00 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 t was also used
2ed10 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f in SQLite versio
2ed20 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d n 2.** for a com
2ed30 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e pletely differen
2ed40 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 t meaning. Soft
2ed50 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 ware that links
2ed60 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 against both.**
2ed70 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 SQLite version 2
2ed80 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 and SQLite vers
2ed90 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 ion 3 should use
2eda0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e SQLITE3_TEXT, n
2edb0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 ot.** SQLITE_TEX
2edc0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 T..*/.#define SQ
2edd0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a LITE_INTEGER 1.
2ede0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
2edf0 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e LOAT 2.#defin
2ee00 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 e SQLITE_BLOB
2ee10 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
2ee20 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 TE_NULL 5.#i
2ee30 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 fdef SQLITE_TEXT
2ee40 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
2ee50 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 TEXT.#else.# def
2ee60 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 ine SQLITE_TEXT
2ee70 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 3.#endif.#de
2ee80 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 fine SQLITE3_TEX
2ee90 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 T 3../*.** C
2eea0 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 API3REF: Result
2eeb0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 Values From A Qu
2eec0 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ery.** KEYWORDS:
2eed0 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 {column access
2eee0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 functions}.** ME
2eef0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2ef00 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 mt.**.** ^These
2ef10 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
2ef20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 information abou
2ef30 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d t a single colum
2ef40 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 n of the current
2ef50 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f .** result row o
2ef60 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 f a query. ^In
2ef70 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 every case the f
2ef80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
2ef90 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
2efa0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
2efb0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 tatement] that i
2efc0 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 s being evaluate
2efd0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f d (the [sqlite3_
2efe0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 stmt*].** that w
2eff0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d as returned from
2f000 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2f010 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f e_v2()] or one o
2f020 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a f its variants).
2f030 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e ** and the secon
2f040 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
2f050 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 e index of the c
2f060 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 olumn for which
2f070 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 information.** s
2f080 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
2f090 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 d. ^The leftmost
2f0a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
2f0b0 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 esult set has th
2f0c0 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 e index 0..** ^T
2f0d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
2f0e0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 umns in the resu
2f0f0 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d lt can be determ
2f100 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 ined using.** [s
2f110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
2f120 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 unt()]..**.** If
2f130 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2f140 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 nt does not curr
2f150 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 ently point to a
2f160 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 valid row, or i
2f170 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 f the.** column
2f180 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
2f190 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c range, the resul
2f1a0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a t is undefined..
2f1b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
2f1c0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 s may only be ca
2f1d0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f lled when the mo
2f1e0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
2f1f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
2f200 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
2f210 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
2f220 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b and neither.** [
2f230 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2f240 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 nor [sqlite3_fi
2f250 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 nalize()] have b
2f260 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 een called subse
2f270 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 quently..** If a
2f280 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
2f290 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
2f2a0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 after [sqlite3_r
2f2b0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
2f2c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2f2d0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c )] or after [sql
2f2e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
2f2f0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d returned.** som
2f300 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
2f310 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 n [SQLITE_ROW],
2f320 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
2f330 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 undefined..** If
2f340 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2f350 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
2f360 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
2f370 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a e3_finalize()].*
2f380 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f * are called fro
2f390 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 m a different th
2f3a0 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f read while any o
2f3b0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
2f3c0 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c .** are pending,
2f3d0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
2f3e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
2f3f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2f400 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
2f410 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
2f420 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 s the.** [SQLITE
2f430 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 _INTEGER | datat
2f440 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 ype code] for th
2f450 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 e initial data t
2f460 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 ype.** of the re
2f470 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 sult column. ^T
2f480 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 he returned valu
2f490 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c e is one of [SQL
2f4a0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a ITE_INTEGER],.**
2f4b0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c [SQLITE_FLOAT],
2f4c0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 [SQLITE_TEXT],
2f4d0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f [SQLITE_BLOB], o
2f4e0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e r [SQLITE_NULL].
2f4f0 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 The value.** r
2f500 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
2f510 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
2f520 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 is only meaning
2f530 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a ful if no type.*
2f540 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 * conversions ha
2f550 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 ve occurred as d
2f560 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 escribed below.
2f570 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f After a type co
2f580 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 nversion,.** the
2f590 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
2f5a0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
2f5b0 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 n_type() is unde
2f5c0 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a fined. Future.*
2f5d0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 * versions of SQ
2f5e0 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 Lite may change
2f5f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
2f600 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2f610 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 ype().** followi
2f620 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 ng a type conver
2f630 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 sion..**.** ^If
2f640 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2f650 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 BLOB or UTF-8 st
2f660 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 ring then the sq
2f670 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2f680 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 es().** routine
2f690 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
2f6a0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
2f6b0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 hat BLOB or stri
2f6c0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 ng..** ^If the r
2f6d0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 esult is a UTF-1
2f6e0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 6 string, then s
2f6f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2f700 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a tes() converts.*
2f710 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 * the string to
2f720 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 UTF-8 and then r
2f730 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
2f740 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e r of bytes..** ^
2f750 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
2f760 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 a numeric value
2f770 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
2f780 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 lumn_bytes() use
2f790 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e s.** [sqlite3_sn
2f7a0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e printf()] to con
2f7b0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 vert that value
2f7c0 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e to a UTF-8 strin
2f7d0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
2f7e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2f7f0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
2f800 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
2f810 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
2f820 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2f830 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 umn_bytes() retu
2f840 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 rns zero..**.**
2f850 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2f860 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
2f870 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 16 string then t
2f880 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
2f890 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 n_bytes16().** r
2f8a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
2f8b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
2f8c0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 es in that BLOB
2f8d0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 or string..** ^I
2f8e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
2f8f0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 a UTF-8 string,
2f900 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2f910 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f umn_bytes16() co
2f920 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 nverts.** the st
2f930 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 ring to UTF-16 a
2f940 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 nd then returns
2f950 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
2f960 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 tes..** ^If the
2f970 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 result is a nume
2f980 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 ric value then s
2f990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2f9a0 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 tes16() uses.**
2f9b0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
2f9c0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 f()] to convert
2f9d0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 that value to a
2f9e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e UTF-16 string an
2f9f0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 d returns.** the
2fa00 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2fa10 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e in that string.
2fa20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2fa30 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e lt is NULL, then
2fa40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2fa50 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e bytes16() return
2fa60 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 s zero..**.** ^T
2fa70 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e he values return
2fa80 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
2fa90 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 olumn_bytes()] a
2faa0 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nd .** [sqlite3_
2fab0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
2fac0 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 ] do not include
2fad0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e the zero termin
2fae0 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 ators at the end
2faf0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e .** of the strin
2fb00 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 g. ^For clarity
2fb10 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 : the values ret
2fb20 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
2fb30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2fb40 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 s()] and [sqlite
2fb50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
2fb60 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 ()] are the numb
2fb70 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 er of.** bytes i
2fb80 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f n the string, no
2fb90 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
2fba0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a characters..**.*
2fbb0 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 * ^Strings retur
2fbc0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
2fbd0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 olumn_text() and
2fbe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2fbf0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 text16(),.** eve
2fc00 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c n empty strings,
2fc10 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f are always zero
2fc20 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 -terminated. ^T
2fc30 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c he return.** val
2fc40 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
2fc50 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f column_blob() fo
2fc60 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 r a zero-length
2fc70 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 BLOB is a NULL p
2fc80 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 ointer..**.** <b
2fc90 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 >Warning:</b> ^T
2fca0 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e he object return
2fcb0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
2fcc0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
2fcd0 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 s an.** [unprote
2fce0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2fcf0 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 ue] object. In
2fd00 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 a multithreaded
2fd10 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 environment,.**
2fd20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 an unprotected s
2fd30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2fd40 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 ect may only be
2fd50 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 used safely with
2fd60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2fd70 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b d_value()] and [
2fd80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
2fd90 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 alue()]..** If t
2fda0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 he [unprotected
2fdb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
2fdc0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
2fdd0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
2fde0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
2fdf0 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 used in any oth
2fe00 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e er way, includin
2fe10 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f g calls.** to ro
2fe20 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c utines like [sql
2fe30 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 ite3_value_int()
2fe40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
2fe50 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
2fe60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2fe70 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 bytes()], the be
2fe80 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 havior is not th
2fe90 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 readsafe..**.**
2fea0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
2feb0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 ttempt to conver
2fec0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 t the value wher
2fed0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 e appropriate.
2fee0 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c ^For.** example,
2fef0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c if the internal
2ff00 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
2ff10 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 is FLOAT and a t
2ff20 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ext result.** is
2ff30 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c requested, [sql
2ff40 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
2ff50 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 is used interna
2ff60 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 lly to perform t
2ff70 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e he.** conversion
2ff80 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
2ff90 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ^(The following
2ffa0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 table details t
2ffb0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a he conversions.*
2ffc0 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 * that are appli
2ffd0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ed:.**.** <block
2ffe0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 quote>.** <table
2fff0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 border="1">.**
30000 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 <tr><th> Interna
30010 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 l<br>Type <th> R
30020 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 equested<br>Type
30030 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f <th> Conversio
30040 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e n.**.** <tr><td>
30050 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 NULL <td> I
30060 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 NTEGER <td> Re
30070 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 sult is 0.** <tr
30080 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
30090 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
300a0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 d> Result is 0.0
300b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
300c0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 LL <td> TEX
300d0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 T <td> Result
300e0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
300f0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 er.** <tr><td>
30100 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 NULL <td> B
30110 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 LOB <td> Resu
30120 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 lt is a NULL poi
30130 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e nter.** <tr><td>
30140 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
30150 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f FLOAT <td> Co
30160 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 nvert from integ
30170 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c er to float.** <
30180 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
30190 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
301a0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 <td> ASCII rende
301b0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 ring of the inte
301c0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ger.** <tr><td>
301d0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 INTEGER <td>
301e0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d BLOB <td> Sam
301f0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 e as INTEGER->TE
30200 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 XT.** <tr><td>
30210 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 FLOAT <td> INT
30220 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 EGER <td> [CAS
30230 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a T] to INTEGER.**
30240 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
30250 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
30260 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e <td> ASCII ren
30270 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c dering of the fl
30280 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
30290 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
302a0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 BLOB <td> [CA
302b0 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c ST] to BLOB.** <
302c0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 tr><td> TEXT
302d0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
302e0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 <td> [CAST] to I
302f0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 NTEGER.** <tr><t
30300 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
30310 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
30320 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a [CAST] to REAL.*
30330 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
30340 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
30350 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 <td> No chang
30360 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 e.** <tr><td> B
30370 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 LOB <td> INTE
30380 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 GER <td> [CAST
30390 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 ] to INTEGER.**
303a0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
303b0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
303c0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 <td> [CAST] to
303d0 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e REAL.** <tr><td>
303e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 BLOB <td>
303f0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 TEXT <td> Ad
30400 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 d a zero termina
30410 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a tor if needed.**
30420 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 </table>.** </b
30430 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a lockquote>)^.**.
30440 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 ** Note that whe
30450 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f n type conversio
30460 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 ns occur, pointe
30470 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 rs returned by p
30480 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f rior.** calls to
30490 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
304a0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f blob(), sqlite3_
304b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 column_text(), a
304c0 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 nd/or.** sqlite3
304d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
304e0 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 may be invalida
304f0 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e ted..** Type con
30500 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 versions and poi
30510 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f nter invalidatio
30520 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a ns might occur.*
30530 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 * in the followi
30540 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 ng cases:.**.**
30550 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 <ul>.** <li> The
30560 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
30570 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 is a BLOB and s
30580 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
30590 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 xt() or.**
305a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
305b0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 ext16() is calle
305c0 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 d. A zero-termi
305d0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 nator might.**
305e0 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 need to be a
305f0 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 dded to the stri
30600 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e ng.</li>.** <li>
30610 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
30620 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 tent is UTF-8 te
30630 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 xt and sqlite3_c
30640 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
30650 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
30660 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
30670 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
30680 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
30690 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
306a0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c to UTF-16.<
306b0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 /li>.** <li> The
306c0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
306d0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 is UTF-16 text
306e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
306f0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a mn_bytes() or.**
30700 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
30710 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 lumn_text() is c
30720 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 alled. The cont
30730 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ent must be conv
30740 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f erted.** to
30750 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 UTF-8.</li>.**
30760 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e </ul>.**.** ^Con
30770 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e versions between
30780 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 UTF-16be and UT
30790 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 F-16le are alway
307a0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 s done in place
307b0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e and do.** not in
307c0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 validate a prior
307d0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 pointer, though
307e0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 of course the c
307f0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 ontent of the bu
30800 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 ffer.** that the
30810 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 prior pointer r
30820 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 eferences will h
30830 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 ave been modifie
30840 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a d. Other kinds.
30850 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e ** of conversion
30860 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 are done in pla
30870 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f ce when it is po
30880 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 ssible, but some
30890 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 times they.** ar
308a0 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 e not possible a
308b0 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 nd in those case
308c0 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 s prior pointers
308d0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 are invalidated
308e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 ..**.** The safe
308f0 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 st policy is to
30900 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 invoke these rou
30910 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 tines.** in one
30920 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
30930 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c ways:.**.** <ul
30940 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
30950 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
30960 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
30970 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
30980 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e ()</li>.** <li>
30990 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
309a0 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 lob() followed b
309b0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
309c0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
309d0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
309e0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f lumn_text16() fo
309f0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
30a00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
30a10 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e ()</li>.** </ul>
30a20 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 .**.** In other
30a30 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c words, you shoul
30a40 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 d call sqlite3_c
30a50 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a olumn_text(),.**
30a60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30a70 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 blob(), or sqlit
30a80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
30a90 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 () first to forc
30aa0 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 e the result.**
30ab0 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 into the desired
30ac0 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e format, then in
30ad0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c voke sqlite3_col
30ae0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a umn_bytes() or.*
30af0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
30b00 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 _bytes16() to fi
30b10 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 nd the size of t
30b20 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e he result. Do n
30b30 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 ot mix calls.**
30b40 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
30b50 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 n_text() or sqli
30b60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
30b70 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a ) with calls to.
30b80 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
30b90 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 n_bytes16(), and
30ba0 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c do not mix call
30bb0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
30bc0 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 umn_text16().**
30bd0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 with calls to sq
30be0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
30bf0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 es()..**.** ^The
30c00 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
30c10 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 ed are valid unt
30c20 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 il a type conver
30c30 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a sion occurs as.*
30c40 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 * described abov
30c50 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c e, or until [sql
30c60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 ite3_step()] or
30c70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
30c80 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
30c90 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 _finalize()] is
30ca0 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 called. ^The me
30cb0 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 mory space used
30cc0 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a to hold strings.
30cd0 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 ** and BLOBs is
30ce0 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 freed automatica
30cf0 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 lly. Do <em>not
30d00 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 </em> pass the p
30d10 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
30d20 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
30d30 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 3_column_blob()]
30d40 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d , [sqlite3_colum
30d50 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 n_text()], etc.
30d60 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 into.** [sqlite3
30d70 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _free()]..**.**
30d80 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c ^(If a memory al
30d90 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f location error o
30da0 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 ccurs during the
30db0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 evaluation of a
30dc0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 ny.** of these r
30dd0 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 outines, a defau
30de0 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 lt value is retu
30df0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 rned. The defau
30e00 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 lt value.** is e
30e10 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 ither the intege
30e20 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e r 0, the floatin
30e30 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 g point number 0
30e40 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a .0, or a NULL.**
30e50 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 pointer. Subse
30e60 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
30e70 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
30e80 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a )] will return.*
30e90 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d * [SQLITE_NOMEM]
30ea0 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 .)^.*/.const voi
30eb0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
30ec0 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 n_blob(sqlite3_s
30ed0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
30ee0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
30ef0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 umn_bytes(sqlite
30f00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
30f10 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
30f20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 column_bytes16(s
30f30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
30f40 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 t iCol);.double
30f50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
30f60 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 ouble(sqlite3_st
30f70 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
30f80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
30f90 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 mn_int(sqlite3_s
30fa0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
30fb0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
30fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
30fd0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t64(sqlite3_stmt
30fe0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f *, int iCol);.co
30ff0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 nst unsigned cha
31000 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
31010 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 n_text(sqlite3_s
31020 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
31030 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
31040 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
31050 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
31060 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
31070 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
31080 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d type(sqlite3_stm
31090 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 t*, int iCol);.s
310a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 qlite3_value *sq
310b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
310c0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ue(sqlite3_stmt*
310d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a , int iCol);../*
310e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
310f0 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 stroy A Prepared
31100 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
31110 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a t.** DESTRUCTOR:
31120 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
31130 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
31140 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 _finalize() func
31150 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 tion is called t
31160 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 o delete a [prep
31170 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
31180 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 .** ^If the most
31190 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 recent evaluati
311a0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d on of the statem
311b0 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 ent encountered
311c0 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 no errors.** or
311d0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 if the statement
311e0 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 is never been e
311f0 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 valuated, then s
31200 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
31210 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c ) returns.** SQL
31220 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 ITE_OK. ^If the
31230 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 most recent eva
31240 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 luation of state
31250 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 ment S failed, t
31260 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 hen.** sqlite3_f
31270 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 inalize(S) retur
31280 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 ns the appropria
31290 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 te [error code]
312a0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 or.** [extended
312b0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a error code]..**.
312c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
312d0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 finalize(S) rout
312e0 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 ine can be calle
312f0 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 d at any point d
31300 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 uring.** the lif
31310 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 e cycle of [prep
31320 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
31330 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 S:.** before sta
31340 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 tement S is ever
31350 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 evaluated, afte
31360 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 r.** one or more
31370 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
31380 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 e3_reset()], or
31390 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a after any call.*
313a0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 * to [sqlite3_st
313b0 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 ep()] regardless
313c0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
313d0 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 ot the statement
313e0 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 has.** complete
313f0 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a d execution..**.
31400 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c ** ^Invoking sql
31410 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 ite3_finalize()
31420 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 on a NULL pointe
31430 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 r is a harmless
31440 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 no-op..**.** The
31450 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
31460 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 t finalize every
31470 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
31480 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 ment] in order t
31490 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 o avoid.** resou
314a0 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 rce leaks. It i
314b0 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 s a grievous err
314c0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 or for the appli
314d0 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f cation to try to
314e0 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 use.** a prepar
314f0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 ed statement aft
31500 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 er it has been f
31510 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 inalized. Any u
31520 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 se of a prepared
31530 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 .** statement af
31540 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 ter it has been
31550 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 finalized can re
31560 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 sult in undefine
31570 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 d and.** undesir
31580 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 able behavior su
31590 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 ch as segfaults
315a0 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 and heap corrupt
315b0 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ion..*/.int sqli
315c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c te3_finalize(sql
315d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
315e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
315f0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 EF: Reset A Prep
31600 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
31610 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a bject.** METHOD:
31620 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
31630 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
31640 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e reset() function
31650 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 is called to re
31660 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 set a [prepared
31670 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 statement].** ob
31680 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 ject back to its
31690 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 initial state,
316a0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 ready to be re-e
316b0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 xecuted..** ^Any
316c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 SQL statement v
316d0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 ariables that ha
316e0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 d values bound t
316f0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 o them using.**
31700 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
31710 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
31720 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 _bind_*() API] r
31730 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 etain their valu
31740 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 es..** Use [sqli
31750 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
31760 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 gs()] to reset t
31770 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a he bindings..**.
31780 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
31790 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 _reset(S)] inter
317a0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 face resets the
317b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
317c0 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 ent] S.** back t
317d0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
317e0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a of its program..
317f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
31800 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
31810 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
31820 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
31830 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
31840 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b nt] S returned [
31850 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b SQLITE_ROW] or [
31860 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a SQLITE_DONE],.**
31870 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f or if [sqlite3_
31880 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 step(S)] has nev
31890 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 er before been c
318a0 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 alled on S,.** t
318b0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 hen [sqlite3_res
318c0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b et(S)] returns [
318d0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
318e0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 * ^If the most r
318f0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
31900 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
31910 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 for the.** [prep
31920 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
31930 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 S indicated an e
31940 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 rror, then.** [s
31950 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
31960 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 returns an appr
31970 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
31980 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode]..**.** ^The
31990 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
319a0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f S)] interface do
319b0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
319c0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 e values.** of a
319d0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ny [sqlite3_bind
319e0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 _blob|bindings]
319f0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 on the [prepared
31a00 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a statement] S..*
31a10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 /.int sqlite3_re
31a20 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 set(sqlite3_stmt
31a30 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
31a40 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 CAPI3REF: Creat
31a50 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 e Or Redefine SQ
31a60 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b L Functions.** K
31a70 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 EYWORDS: {functi
31a80 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
31a90 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 ines}.** KEYWORD
31aa0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
31ab0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
31ac0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 tion}.** KEYWORD
31ad0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
31ae0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
31af0 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 tions}.** METHOD
31b00 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
31b10 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
31b20 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b (collectively k
31b30 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f nown as "functio
31b40 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 n creation routi
31b50 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 nes").** are use
31b60 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e d to add SQL fun
31b70 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
31b80 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 ates or to redef
31b90 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 ine the behavior
31ba0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 .** of existing
31bb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 SQL functions or
31bc0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 aggregates. Th
31bd0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 e only differenc
31be0 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 es between.** th
31bf0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
31c00 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 the text encodi
31c10 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a ng expected for.
31c20 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 ** the second pa
31c30 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d rameter (the nam
31c40 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f e of the functio
31c50 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 n being created)
31c60 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 .** and the pres
31c70 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 ence or absence
31c80 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 of a destructor
31c90 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 callback for.**
31ca0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
31cb0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a data pointer..**
31cc0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 .** ^The first p
31cd0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
31ce0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
31cf0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 tion] to which t
31d00 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 he SQL.** functi
31d10 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 on is to be adde
31d20 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 d. ^If an appli
31d30 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 cation uses more
31d40 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 than one databa
31d50 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
31d60 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f then applicatio
31d70 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
31d80 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 nctions must be
31d90 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 added.** to each
31da0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
31db0 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e tion separately.
31dc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f .**.** ^The seco
31dd0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
31de0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
31df0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
31e00 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a be created or.**
31e10 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 redefined. ^Th
31e20 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
31e30 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 name is limited
31e40 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 to 255 bytes in
31e50 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 a UTF-8.** repre
31e60 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 sentation, exclu
31e70 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f sive of the zero
31e80 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e -terminator. ^N
31e90 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d ote that the nam
31ea0 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 e.** length limi
31eb0 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 t is in UTF-8 by
31ec0 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 tes, not charact
31ed0 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 ers nor UTF-16 b
31ee0 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 ytes. .** ^Any
31ef0 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 attempt to creat
31f00 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 e a function wit
31f10 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a h a longer name.
31f20 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 ** will result i
31f30 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 n [SQLITE_MISUSE
31f40 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 ] being returned
31f50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 ..**.** ^The thi
31f60 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 rd parameter (nA
31f70 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 rg).** is the nu
31f80 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
31f90 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 s that the SQL f
31fa0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
31fb0 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e gregate takes. ^
31fc0 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 If this paramete
31fd0 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 r is -1, then th
31fe0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
31ff0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d r.** aggregate m
32000 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 ay take any numb
32010 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
32020 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 between 0 and th
32030 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 e limit.** set b
32040 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 y [sqlite3_limit
32050 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ]([SQLITE_LIMIT_
32060 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 FUNCTION_ARG]).
32070 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a If the third.**
32080 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 parameter is le
32090 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 ss than -1 or gr
320a0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 eater than 127 t
320b0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
320c0 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 is.** undefined
320d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
320e0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 rth parameter, e
320f0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 TextRep, specifi
32100 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 es what.** [SQLI
32110 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 TE_UTF8 | text e
32120 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 ncoding] this SQ
32130 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 L function prefe
32140 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 rs for.** its pa
32150 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 rameters. The a
32160 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
32170 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d d set this param
32180 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 eter to.** [SQLI
32190 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 TE_UTF16LE] if t
321a0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c he function impl
321b0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b ementation invok
321c0 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f es .** [sqlite3_
321d0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 value_text16le()
321e0 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f ] on an input, o
321f0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 r [SQLITE_UTF16B
32200 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 E] if the.** imp
32210 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f lementation invo
32220 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c kes [sqlite3_val
32230 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f ue_text16be()] o
32240 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a n an input, or.*
32250 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d * [SQLITE_UTF16]
32260 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c if [sqlite3_val
32270 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 ue_text16()] is
32280 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 used, or [SQLITE
32290 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 _UTF8].** otherw
322a0 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 ise. ^The same
322b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 SQL function may
322c0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d be registered m
322d0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 ultiple times us
322e0 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 ing.** different
322f0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
32300 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 encodings, with
32310 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d different implem
32320 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a entations for.**
32330 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a each encoding..
32340 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c ** ^When multipl
32350 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
32360 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
32370 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c nction are avail
32380 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 able, SQLite.**
32390 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e will pick the on
323a0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 e that involves
323b0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 the least amount
323c0 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 of data convers
323d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ion..**.** ^The
323e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
323f0 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 may optionally
32400 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 be ORed with [SQ
32410 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 LITE_DETERMINIST
32420 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c IC].** to signal
32430 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 that the functi
32440 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 on will always r
32450 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 eturn the same r
32460 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 esult given.** t
32470 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 he same inputs w
32480 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 ithin a single S
32490 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d QL statement. M
324a0 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ost SQL function
324b0 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 s are.** determi
324c0 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 nistic. The bui
324d0 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d lt-in [random()]
324e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 SQL function is
324f0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 an example of a
32500 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 .** function tha
32510 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 t is not determi
32520 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c nistic. The SQL
32530 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 ite query planne
32540 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 r is able to.**
32550 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e perform addition
32560 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 al optimizations
32570 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 on deterministi
32580 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 c functions, so
32590 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 use.** of the [S
325a0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 QLITE_DETERMINIS
325b0 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 TIC] flag is rec
325c0 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 ommended where p
325d0 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e ossible..**.** ^
325e0 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d (The fifth param
325f0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 eter is an arbit
32600 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 rary pointer. T
32610 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
32620 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 n of the.** func
32630 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 tion can gain ac
32640 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 cess to this poi
32650 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 nter using [sqli
32660 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d te3_user_data()]
32670 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
32680 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e ixth, seventh an
32690 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 d eighth paramet
326a0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 ers, xFunc, xSte
326b0 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 p and xFinal, ar
326c0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f e.** pointers to
326d0 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 C-language func
326e0 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 tions that imple
326f0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e ment the SQL fun
32700 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
32710 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 egate. ^A scalar
32720 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 SQL function re
32730 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d quires an implem
32740 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 entation of the
32750 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 xFunc.** callbac
32760 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 k only; NULL poi
32770 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 nters must be pa
32780 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 ssed as the xSte
32790 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 p and xFinal.**
327a0 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 parameters. ^An
327b0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
327c0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
327d0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f an implementatio
327e0 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e n of xStep.** an
327f0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c d xFinal and NUL
32800 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 L pointer must b
32810 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 e passed for xFu
32820 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 nc. ^To delete a
32830 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 n existing.** SQ
32840 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 L function or ag
32850 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 gregate, pass NU
32860 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 LL pointers for
32870 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 all three functi
32880 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e on.** callbacks.
32890 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 .**.** ^(If the
328a0 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 ninth parameter
328b0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 to sqlite3_creat
328c0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 e_function_v2()
328d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 is not NULL,.**
328e0 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 then it is destr
328f0 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 uctor for the ap
32900 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 plication data p
32910 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 ointer. .** The
32920 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e destructor is in
32930 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 voked when the f
32940 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 unction is delet
32950 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 ed, either by be
32960 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 ing.** overloade
32970 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 d or when the da
32980 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
32990 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e n closes.)^.** ^
329a0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
329b0 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 s also invoked i
329c0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a f the call to.**
329d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
329e0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 function_v2() fa
329f0 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 ils..** ^When th
32a00 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c e destructor cal
32a10 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e lback of the ten
32a20 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
32a30 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 invoked, it.** i
32a40 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c s passed a singl
32a50 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
32a60 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
32a70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 e application da
32a80 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 ta .** pointer w
32a90 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 hich was the fif
32aa0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
32ab0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
32ac0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a unction_v2()..**
32ad0 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 .** ^It is permi
32ae0 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 tted to register
32af0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d multiple implem
32b00 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 entations of the
32b10 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f same.** functio
32b20 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 ns with the same
32b30 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 name but with e
32b40 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 ither differing
32b50 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 numbers of.** ar
32b60 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 guments or diffe
32b70 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 ring preferred t
32b80 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 ext encodings.
32b90 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 ^SQLite will use
32ba0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
32bb0 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 tation that most
32bc0 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 closely matches
32bd0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 the way in whic
32be0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e h the.** SQL fun
32bf0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 ction is used.
32c00 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c ^A function impl
32c10 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 ementation with
32c20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a a non-negative.*
32c30 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 * nArg parameter
32c40 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 is a better mat
32c50 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 ch than a functi
32c60 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
32c70 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 n with.** a nega
32c80 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 tive nArg. ^A f
32c90 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
32ca0 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 e preferred text
32cb0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 encoding.** mat
32cc0 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 ches the databas
32cd0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 e encoding is a
32ce0 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 better.** match
32cf0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
32d00 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
32d10 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e ng is different.
32d20 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f .** ^A functio
32d30 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
32d40 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 ding difference
32d50 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 is between UTF16
32d60 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a le and UTF16be.*
32d70 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 * is a closer ma
32d80 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 tch than a funct
32d90 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e ion where the en
32da0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 coding differenc
32db0 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 e is.** between
32dc0 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a UTF8 and UTF16..
32dd0 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 **.** ^Built-in
32de0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 functions may be
32df0 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e overloaded by n
32e00 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 ew application-d
32e10 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 efined functions
32e20 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c ..**.** ^An appl
32e30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
32e40 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d function is perm
32e50 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 itted to call ot
32e60 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e her.** SQLite in
32e70 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 terfaces. Howev
32e80 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d er, such calls m
32e90 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 ust not.** close
32ea0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
32eb0 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e nnection nor fin
32ec0 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 alize or reset t
32ed0 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 he prepared.** s
32ee0 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 tatement in whic
32ef0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 h the function i
32f00 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e s running..*/.in
32f10 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
32f20 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c _function(. sql
32f30 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
32f40 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
32f50 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
32f60 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
32f70 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
32f80 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
32f90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
32fa0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
32fb0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
32fc0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
32fd0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
32fe0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
32ff0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
33000 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
33010 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
33020 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
33030 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 16(. sqlite3 *d
33040 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 b,. const void
33050 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
33060 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
33070 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
33080 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
33090 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
330a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
330b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
330c0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
330d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
330e0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
330f0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
33100 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
33110 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e _context*).);.in
33120 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
33130 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 _function_v2(.
33140 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
33150 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
33160 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
33170 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
33180 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
33190 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
331a0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
331b0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
331c0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
331d0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
331e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
331f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
33200 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
33210 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
33220 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 xt*),. void(*xD
33230 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 estroy)(void*).)
33240 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
33250 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 F: Text Encoding
33260 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f s.**.** These co
33270 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e nstant define in
33280 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 teger codes that
33290 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 represent the v
332a0 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 arious.** text e
332b0 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 ncodings support
332c0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f ed by SQLite..*/
332d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
332e0 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 UTF8 1
332f0 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 /* IMP: R-37
33300 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 514-35566 */.#de
33310 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
33320 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20 6LE 2
33330 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d /* IMP: R-03371-
33340 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 37637 */.#define
33350 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 SQLITE_UTF16BE
33360 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 3 /* I
33370 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 MP: R-51971-3415
33380 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 4 */.#define SQL
33390 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 ITE_UTF16
333a0 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 4 /* Use n
333b0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
333c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
333d0 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 TE_ANY
333e0 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 5 /* Deprec
333f0 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ated */.#define
33400 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
33410 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 GNED 8 /* sq
33420 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
33430 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a lation only */..
33440 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
33450 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a Function Flags.*
33460 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
33470 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 ants may be ORed
33480 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 together with t
33490 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 he .** [SQLITE_U
334a0 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 TF8 | preferred
334b0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 text encoding] a
334c0 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 s the fourth arg
334d0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c ument.** to [sql
334e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
334f0 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 tion()], [sqlite
33500 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
33510 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 n16()], or.** [s
33520 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
33530 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f nction_v2()]..*/
33540 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
33550 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 DETERMINISTIC
33560 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 0x800../*.** CA
33570 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 PI3REF: Deprecat
33580 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 ed Functions.**
33590 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a DEPRECATED.**.**
335a0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
335b0 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 are [deprecated
335c0 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 ]. In order to
335d0 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b maintain.** back
335e0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
335f0 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 ity with older c
33600 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 ode, these funct
33610 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a ions continue .*
33620 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 * to be supporte
33630 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 d. However, new
33640 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 applications sh
33650 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 ould avoid.** th
33660 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 e use of these f
33670 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e unctions. To en
33680 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d courage programm
33690 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 ers to avoid.**
336a0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c these functions,
336b0 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 we will not exp
336c0 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 lain what they d
336d0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 o..*/.#ifndef SQ
336e0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 LITE_OMIT_DEPREC
336f0 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 ATED.SQLITE_DEPR
33700 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
33710 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 e3_aggregate_cou
33720 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 nt(sqlite3_conte
33730 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 xt*);.SQLITE_DEP
33740 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
33750 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 te3_expired(sqli
33760 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
33770 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
33780 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 t sqlite3_transf
33790 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 er_bindings(sqli
337a0 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 te3_stmt*, sqlit
337b0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 e3_stmt*);.SQLIT
337c0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
337d0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f sqlite3_global_
337e0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 recover(void);.S
337f0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
33800 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 void sqlite3_th
33810 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 read_cleanup(voi
33820 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 d);.SQLITE_DEPRE
33830 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
33840 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 3_memory_alarm(v
33850 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
33860 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c ite3_int64,int),
33870 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
33880 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c void*,sql
33890 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e ite3_int64);.#en
338a0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
338b0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 REF: Obtaining S
338c0 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 QL Values.** MET
338d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c HOD: sqlite3_val
338e0 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c ue.**.** The C-l
338f0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e anguage implemen
33900 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 tation of SQL fu
33910 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
33920 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 egates uses.** t
33930 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 his set of inter
33940 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f face routines to
33950 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 access the para
33960 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a meter values on.
33970 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 ** the function
33980 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a or aggregate. .
33990 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 **.** The xFunc
339a0 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 (for scalar func
339b0 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 tions) or xStep
339c0 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 (for aggregates)
339d0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 parameters.** t
339e0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
339f0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
33a00 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
33a10 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
33a20 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 ** define callba
33a30 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 cks that impleme
33a40 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
33a50 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
33a60 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 tes..** The 3rd
33a70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
33a80 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 se callbacks is
33a90 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
33aa0 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 ters to.** [prot
33ab0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
33ac0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 lue] objects. T
33ad0 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c here is one [sql
33ae0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
33af0 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 ct for.** each p
33b00 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
33b10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 SQL function. T
33b20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
33b30 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 e used to.** ext
33b40 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d ract values from
33b50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
33b60 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a lue] objects..**
33b70 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
33b80 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 es work only wit
33b90 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c h [protected sql
33ba0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
33bb0 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 cts..** Any atte
33bc0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 mpt to use these
33bd0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 routines on an
33be0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
33bf0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f ite3_value].** o
33c00 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e bject results in
33c10 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
33c20 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ior..**.** ^Thes
33c30 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
33c40 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f just like the co
33c50 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c rresponding [col
33c60 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
33c70 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 ions].** except
33c80 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 that these routi
33c90 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c nes take a singl
33ca0 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c e [protected sql
33cb0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
33cc0 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e ct.** pointer in
33cd0 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 stead of a [sqli
33ce0 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 te3_stmt*] point
33cf0 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 er and an intege
33d00 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e r column number.
33d10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
33d20 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
33d30 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 () interface ext
33d40 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 racts a UTF-16 s
33d50 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 tring.** in the
33d60 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 native byte-orde
33d70 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 r of the host ma
33d80 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 chine. ^The.**
33d90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
33da0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c xt16be() and sql
33db0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
33dc0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 6le() interfaces
33dd0 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d .** extract UTF-
33de0 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 16 strings as bi
33df0 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 g-endian and lit
33e00 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 tle-endian respe
33e10 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e ctively..**.** ^
33e20 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c (The sqlite3_val
33e30 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 ue_numeric_type(
33e40 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 ) interface atte
33e50 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a mpts to apply.**
33e60 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 numeric affinit
33e70 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 y to the value.
33e80 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 This means that
33e90 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a an attempt is.*
33ea0 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 * made to conver
33eb0 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 t the value to a
33ec0 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f n integer or flo
33ed0 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 ating point. If
33ee0 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 .** such a conve
33ef0 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c rsion is possibl
33f00 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f e without loss o
33f10 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 f information (i
33f20 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 n other.** words
33f30 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 , if the value i
33f40 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 s a string that
33f50 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d looks like a num
33f60 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ber).** then the
33f70 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 conversion is p
33f80 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 erformed. Other
33f90 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 wise no conversi
33fa0 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 on occurs..** Th
33fb0 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 e [SQLITE_INTEGE
33fc0 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 R | datatype] af
33fd0 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 ter conversion i
33fe0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a s returned.)^.**
33ff0 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 .** Please pay p
34000 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 articular attent
34010 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 ion to the fact
34020 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 that the pointer
34030 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f returned.** fro
34040 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 m [sqlite3_value
34050 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 _blob()], [sqlit
34060 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d e3_value_text()]
34070 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
34080 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d _value_text16()]
34090 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 can be invalida
340a0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 ted by a subsequ
340b0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ent call to.** [
340c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
340d0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 tes()], [sqlite3
340e0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 _value_bytes16()
340f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
34100 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
34110 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
34120 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a text16()]..**.**
34130 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
34140 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
34150 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
34160 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 ead as.** the SQ
34170 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 L function that
34180 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 supplied the [sq
34190 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 lite3_value*] pa
341a0 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e rameters..*/.con
341b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
341c0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 _value_blob(sqli
341d0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
341e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 sqlite3_value_b
341f0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c ytes(sqlite3_val
34200 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ue*);.int sqlite
34210 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 3_value_bytes16(
34220 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
34230 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f .double sqlite3_
34240 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c value_double(sql
34250 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e ite3_value*);.in
34260 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
34270 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 int(sqlite3_valu
34280 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 e*);.sqlite3_int
34290 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 64 sqlite3_value
342a0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 _int64(sqlite3_v
342b0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e alue*);.const un
342c0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c signed char *sql
342d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
342e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
342f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
34300 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
34310 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 6(sqlite3_value*
34320 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
34330 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
34340 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 t16le(sqlite3_va
34350 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 lue*);.const voi
34360 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
34370 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 _text16be(sqlite
34380 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 3_value*);.int s
34390 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 qlite3_value_typ
343a0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
343b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 );.int sqlite3_v
343c0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 alue_numeric_typ
343d0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
343e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
343f0 45 46 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20 EF: Finding The
34400 53 75 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56 Subtype Of SQL V
34410 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a alues.** METHOD:
34420 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a sqlite3_value.*
34430 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
34440 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56 _value_subtype(V
34450 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 ) function retur
34460 6e 73 20 74 68 65 20 73 75 62 74 79 70 65 20 66 ns the subtype f
34470 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 or.** an [applic
34480 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
34490 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 L function] argu
344a0 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62 ment V. The sub
344b0 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 type.** informat
344c0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
344d0 74 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65 to pass a limite
344e0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 d amount of cont
344f0 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 ext from.** one
34500 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
34510 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68 another. Use th
34520 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c e [sqlite3_resul
34530 74 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 t_subtype()].**
34540 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74 routine to set t
34550 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 20 74 he subtype for t
34560 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
34570 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 of an SQL functi
34580 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 on..**.** SQLite
34590 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 makes no use of
345a0 20 73 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e subtype itself.
345b0 20 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73 It merely pass
345c0 65 73 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a es the subtype.*
345d0 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c * from the resul
345e0 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 t of one [applic
345f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
34600 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f L function] into
34610 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 the.** input of
34620 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 another..*/.uns
34630 69 67 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65 igned int sqlite
34640 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 3_value_subtype(
34650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
34660 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
34670 3a 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 : Copy And Free
34680 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 SQL Values.** ME
34690 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 THOD: sqlite3_va
346a0 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 lue.**.** ^The s
346b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 qlite3_value_dup
346c0 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 (V) interface ma
346d0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
346e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
346f0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e ].** object D an
34700 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e d returns a poin
34710 74 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 ter to that copy
34720 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 . ^The [sqlite3
34730 5f 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 _value] returned
34740 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 .** is a [protec
34750 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
34760 65 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 e] object even i
34770 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e f the input is n
34780 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 ot..** ^The sqli
34790 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 te3_value_dup(V)
347a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
347b0 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 ns NULL if V is
347c0 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 NULL or if a.**
347d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
347e0 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e n fails..**.** ^
347f0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
34800 65 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 e_free(V) interf
34810 61 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 ace frees an [sq
34820 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
34830 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c ect.** previousl
34840 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
34850 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 [sqlite3_value_d
34860 75 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 up()]. ^If V is
34870 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
34880 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ** then sqlite3_
34890 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 value_free(V) is
348a0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f a harmless no-o
348b0 70 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 61 p..*/.sqlite3_va
348c0 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c lue *sqlite3_val
348d0 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c ue_dup(const sql
348e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f ite3_value*);.vo
348f0 69 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 id sqlite3_value
34900 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 _free(sqlite3_va
34910 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lue*);../*.** CA
34920 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 PI3REF: Obtain A
34930 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f ggregate Functio
34940 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 n Context.** MET
34950 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e HOD: sqlite3_con
34960 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 text.**.** Imple
34970 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 mentations of ag
34980 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
34990 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a tions use this.*
349a0 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c * routine to all
349b0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 ocate memory for
349c0 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 storing their s
349d0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tate..**.** ^The
349e0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 first time the
349f0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
34a00 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 e_context(C,N) r
34a10 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 outine is called
34a20 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 .** for a parti
34a30 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 cular aggregate
34a40 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 function, SQLite
34a50 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 .** allocates N
34a60 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 of memory, zeroe
34a70 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 s out that memor
34a80 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 y, and returns a
34a90 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 pointer.** to t
34aa0 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e he new memory. ^
34ab0 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 On second and su
34ac0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
34ad0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 o.** sqlite3_agg
34ae0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
34af0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 for the same ag
34b00 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
34b10 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 instance,.** th
34b20 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 e same buffer is
34b30 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 returned. Sqli
34b40 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
34b50 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 ntext() is norma
34b60 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e lly.** called on
34b70 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f ce for each invo
34b80 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 cation of the xS
34b90 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 tep callback and
34ba0 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 then one.** las
34bb0 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 t time when the
34bc0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 xFinal callback
34bd0 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 is invoked. ^(W
34be0 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 hen no rows matc
34bf0 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 h.** an aggregat
34c00 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 e query, the xSt
34c10 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 ep() callback of
34c20 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 the aggregate f
34c30 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 unction.** imple
34c40 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 mentation is nev
34c50 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 er called and xF
34c60 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 inal() is called
34c70 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a exactly once..*
34c80 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 * In those cases
34c90 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 , sqlite3_aggreg
34ca0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 ate_context() mi
34cb0 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f ght be called fo
34cc0 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 r the.** first t
34cd0 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 ime from within
34ce0 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a xFinal().)^.**.*
34cf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 * ^The sqlite3_a
34d00 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
34d10 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 (C,N) routine re
34d20 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
34d30 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 nter .** when fi
34d40 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 rst called if N
34d50 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 is less than or
34d60 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 equal to zero or
34d70 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 if a memory.**
34d80 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f allocate error o
34d90 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 ccurs..**.** ^(T
34da0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 he amount of spa
34db0 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 ce allocated by
34dc0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
34dd0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 e_context(C,N) i
34de0 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 s.** determined
34df0 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 by the N paramet
34e00 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 er on first succ
34e10 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 essful call. Ch
34e20 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 anging the.** va
34e30 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 lue of N in subs
34e40 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 equent call to s
34e50 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
34e60 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 _context() withi
34e70 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 n.** the same ag
34e80 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
34e90 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e instance will n
34ea0 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 ot resize the me
34eb0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 mory.** allocati
34ec0 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 on.)^ Within th
34ed0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 e xFinal callbac
34ee0 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 k, it is customa
34ef0 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 ry to set.** N=0
34f00 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c in calls to sql
34f10 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
34f20 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 ontext(C,N) so t
34f30 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 hat no .** point
34f40 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f less memory allo
34f50 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a cations occur..*
34f60 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 *.** ^SQLite aut
34f70 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 omatically frees
34f80 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
34f90 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c cated by .** sql
34fa0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
34fb0 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 ontext() when th
34fc0 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 e aggregate quer
34fd0 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a y concludes..**.
34fe0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 ** The first par
34ff0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 ameter must be a
35000 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
35010 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 [sqlite3_context
35020 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 | SQL function
35030 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 context] that is
35040 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
35050 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 eter.** to the x
35060 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 Step or xFinal c
35070 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 allback routine
35080 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 that implements
35090 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a the aggregate.**
350a0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
350b0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 This routine mu
350c0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f st be called fro
350d0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 m the same threa
350e0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 d in which.** th
350f0 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 e aggregate SQL
35100 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
35110 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ing..*/.void *sq
35120 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
35130 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f context(sqlite3_
35140 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 context*, int nB
35150 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ytes);../*.** CA
35160 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 PI3REF: User Dat
35170 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a a For Functions.
35180 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
35190 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a e3_context.**.**
351a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 ^The sqlite3_us
351b0 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 er_data() interf
351c0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f ace returns a co
351d0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 py of.** the poi
351e0 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 nter that was th
351f0 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 e pUserData para
35200 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 meter (the 5th p
35210 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 arameter).** of
35220 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
35230 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a ate_function()].
35240 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
35250 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
35260 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 6()] routines th
35270 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a at originally.**
35280 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 registered the
35290 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
352a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a ned function..**
352b0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
352c0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
352d0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
352e0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
352f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
35300 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
35310 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f n is running..*/
35320 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 .void *sqlite3_u
35330 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 ser_data(sqlite3
35340 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a _context*);../*.
35350 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 ** CAPI3REF: Dat
35360 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
35370 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a For Functions.*
35380 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
35390 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 3_context.**.**
353a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e ^The sqlite3_con
353b0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 text_db_handle()
353c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
353d0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 ns a copy of.**
353e0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 the pointer to t
353f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
35400 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 nection] (the 1s
35410 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 t parameter).**
35420 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
35430 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
35440 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
35450 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
35460 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 on16()] routines
35470 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 that originally
35480 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 .** registered t
35490 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
354a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
354b0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c .*/.sqlite3 *sql
354c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f ite3_context_db_
354d0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 handle(sqlite3_c
354e0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a ontext*);../*.**
354f0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 CAPI3REF: Funct
35500 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 ion Auxiliary Da
35510 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ta.** METHOD: sq
35520 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a lite3_context.**
35530 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
35540 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 ons may be used
35550 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 by (non-aggregat
35560 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 e) SQL functions
35570 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 to.** associate
35580 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 metadata with a
35590 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 rgument values.
355a0 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 If the same valu
355b0 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a e is passed to.*
355c0 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 * multiple invoc
355d0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
355e0 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 me SQL function
355f0 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 during query exe
35600 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a cution, under.**
35610 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e some circumstan
35620 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 ces the associat
35630 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 ed metadata may
35640 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 be preserved. A
35650 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 n example.** of
35660 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 where this might
35670 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e be useful is in
35680 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 a regular-expre
35690 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a ssion matching.*
356a0 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 * function. The
356b0 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e compiled version
356c0 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 of the regular
356d0 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 expression can b
356e0 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d e stored as.** m
356f0 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 etadata associat
35700 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74 74 ed with the patt
35710 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a ern string. .**
35720 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 Then as long as
35730 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 the pattern str
35740 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 ing remains the
35750 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d same,.** the com
35760 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 piled regular ex
35770 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 pression can be
35780 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 reused on multip
35790 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e le.** invocation
357a0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
357b0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 nction..**.** ^T
357c0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 he sqlite3_get_a
357d0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
357e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
357f0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 nter to the meta
35800 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 data.** associat
35810 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 ed by the sqlite
35820 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_set_auxdata()
35830 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 function with th
35840 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a e Nth argument.*
35850 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 * value to the a
35860 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
35870 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 ed function. ^If
35880 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 there is no met
35890 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 adata.** associa
358a0 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75 6e ted with the fun
358b0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 ction argument,
358c0 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 this sqlite3_get
358d0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 _auxdata() inter
358e0 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 face.** returns
358f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
35900 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
35910 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 e3_set_auxdata(C
35920 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 ,N,P,X) interfac
35930 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 e saves P as met
35940 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d adata for the N-
35950 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f th.** argument o
35960 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
35970 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
35980 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 on. ^Subsequent
35990 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c .** calls to sql
359a0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
359b0 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 (C,N) return P f
359c0 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 rom the most rec
359d0 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 ent.** sqlite3_s
359e0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 et_auxdata(C,N,P
359f0 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 ,X) call if the
35a00 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69 6c metadata is stil
35a10 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 l valid or.** NU
35a20 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 LL if the metada
35a30 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 ta has been disc
35a40 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 arded..** ^After
35a50 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 each call to sq
35a60 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
35a70 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 a(C,N,P,X) where
35a80 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a X is not NULL,.
35a90 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 ** SQLite will i
35aa0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 nvoke the destru
35ab0 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 ctor function X
35ac0 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 with parameter P
35ad0 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 exactly.** once
35ae0 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 , when the metad
35af0 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65 64 ata is discarded
35b00 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 ..** SQLite is f
35b10 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 ree to discard t
35b20 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 he metadata at a
35b30 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 ny time, includi
35b40 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e ng: <ul>.** <li>
35b50 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 when the corres
35b60 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e ponding function
35b70 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 parameter chang
35b80 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 es, or.** <li> w
35b90 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 hen [sqlite3_res
35ba0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 et()] or [sqlite
35bb0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 3_finalize()] is
35bc0 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a called for the.
35bd0 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 ** SQL stat
35be0 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 ement, or.** <li
35bf0 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 > when sqlite3_s
35c00 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 et_auxdata() is
35c10 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e invoked again on
35c20 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 the same parame
35c30 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 ter, or.** <li>
35c40 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 during the origi
35c50 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f nal sqlite3_set_
35c60 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 auxdata() call w
35c70 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a hen a memory .**
35c80 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e allocation
35c90 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c error occurs. <
35ca0 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 /ul>)^.**.** Not
35cb0 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 e the last bulle
35cc0 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e t in particular.
35cd0 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 The destructor
35ce0 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 X in .** sqlite
35cf0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 3_set_auxdata(C,
35d00 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 N,P,X) might be
35d10 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 called immediate
35d20 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a ly, before the.*
35d30 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 * sqlite3_set_au
35d40 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 xdata() interfac
35d50 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 e even returns.
35d60 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 Hence sqlite3_s
35d70 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 et_auxdata().**
35d80 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 should be called
35d90 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 near the end of
35da0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d the function im
35db0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 plementation and
35dc0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e the.** function
35dd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
35de0 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 should not make
35df0 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 any use of P aft
35e00 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 er.** sqlite3_se
35e10 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73 20 t_auxdata() has
35e20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a been called..**.
35e30 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 ** ^(In practice
35e40 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 , metadata is pr
35e50 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 eserved between
35e60 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 function calls f
35e70 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 or.** function p
35e80 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 arameters that a
35e90 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 re compile-time
35ea0 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 constants, inclu
35eb0 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 ding literal.**
35ec0 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 values and [para
35ed0 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 meters] and expr
35ee0 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 essions composed
35ef0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 from the same.)
35f00 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ^.**.** These ro
35f10 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 utines must be c
35f20 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 alled from the s
35f30 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 ame thread in wh
35f40 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 ich.** the SQL f
35f50 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
35f60 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c ng..*/.void *sql
35f70 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
35f80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
35f90 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 *, int N);.void
35fa0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
35fb0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ata(sqlite3_cont
35fc0 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 ext*, int N, voi
35fd0 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 d*, void (*)(voi
35fe0 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 d*));.../*.** CA
35ff0 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 PI3REF: Constant
36000 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 s Defining Speci
36010 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 al Destructor Be
36020 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 havior.**.** The
36030 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 se are special v
36040 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 alues for the de
36050 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 structor that is
36060 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 passed in as th
36070 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d e.** final argum
36080 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 ent to routines
36090 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 like [sqlite3_re
360a0 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e sult_blob()]. ^
360b0 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f If the destructo
360c0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 r.** argument is
360d0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 SQLITE_STATIC,
360e0 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 it means that th
360f0 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 e content pointe
36100 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a r is constant.**
36110 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 and will never
36120 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 change. It does
36130 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 not need to be
36140 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 destroyed. ^The
36150 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 .** SQLITE_TRANS
36160 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 IENT value means
36170 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e that the conten
36180 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 t will likely ch
36190 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e ange in.** the n
361a0 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 ear future and t
361b0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c hat SQLite shoul
361c0 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 d make its own p
361d0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a rivate copy of.*
361e0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 * the content be
361f0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a fore returning..
36200 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 **.** The typede
36210 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 f is necessary t
36220 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 o work around pr
36230 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 oblems in certai
36240 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 n.** C++ compile
36250 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 rs..*/.typedef v
36260 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 oid (*sqlite3_de
36270 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 structor_type)(v
36280 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 oid*);.#define S
36290 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 QLITE_STATIC
362a0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 ((sqlite3_dest
362b0 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 ructor_type)0).#
362c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
362d0 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 ANSIENT ((sqli
362e0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 te3_destructor_t
362f0 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 ype)-1)../*.** C
36300 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 API3REF: Setting
36310 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 The Result Of A
36320 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a n SQL Function.*
36330 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
36340 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 3_context.**.**
36350 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
36360 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 re used by the x
36370 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 Func or xFinal c
36380 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a allbacks that.**
36390 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 implement SQL f
363a0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
363b0 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a regates. See.**
363c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
363d0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 _function()] and
363e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
363f0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a _function16()].*
36400 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c * for additional
36410 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
36420 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
36430 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 ons work very mu
36440 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 ch like the [par
36450 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 ameter binding]
36460 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e family of.** fun
36470 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 ctions used to b
36480 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f ind values to ho
36490 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e st parameters in
364a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
364b0 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 ents..** Refer t
364c0 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d o the [SQL param
364d0 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 eter] documentat
364e0 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ion for addition
364f0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
36500 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
36510 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 e3_result_blob()
36520 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
36530 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a the result from.
36540 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ** an applicatio
36550 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
36560 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f on to be the BLO
36570 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 B whose content
36580 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f is pointed.** to
36590 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 by the second p
365a0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 arameter and whi
365b0 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f ch is N bytes lo
365c0 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 ng where N is th
365d0 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d e.** third param
365e0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 eter..**.** ^The
365f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36600 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 20 61 6e zeroblob(C,N) an
36610 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
36620 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 43 2c 4e 29 _zeroblob64(C,N)
36630 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 73 .** interfaces s
36640 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 et the result of
36650 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
36660 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
36670 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 42 4c 4f n to be.** a BLO
36680 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c B containing all
36690 20 7a 65 72 6f 20 62 79 74 65 73 20 61 6e 64 20 zero bytes and
366a0 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2e N bytes in size.
366b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
366c0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c te3_result_doubl
366d0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 e() interface se
366e0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 ts the result fr
366f0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 om.** an applica
36700 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
36710 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c ction to be a fl
36720 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
36730 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 ue specified.**
36740 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d by its 2nd argum
36750 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ent..**.** ^The
36760 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
36770 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 rror() and sqlit
36780 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
36790 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 6() functions.**
367a0 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 cause the imple
367b0 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 mented SQL funct
367c0 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 ion to throw an
367d0 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 exception..** ^S
367e0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 QLite uses the s
367f0 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f tring pointed to
36800 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 by the.** 2nd p
36810 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 arameter of sqli
36820 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
36830 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 () or sqlite3_re
36840 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a sult_error16().*
36850 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 * as the text of
36860 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
36870 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 e. ^SQLite inte
36880 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 rprets the error
36890 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 .** message stri
368a0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ng from sqlite3_
368b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 result_error() a
368c0 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 s UTF-8. ^SQLite
368d0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 .** interprets t
368e0 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 he string from s
368f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
36900 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 ror16() as UTF-1
36910 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 6 in native.** b
36920 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 yte order. ^If
36930 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
36940 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
36950 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a esult_error().**
36960 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
36970 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 lt_error16() is
36980 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 negative then SQ
36990 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 Lite takes as th
369a0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 e error.** messa
369b0 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 ge all text up t
369c0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 hrough the first
369d0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e zero character.
369e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 .** ^If the thir
369f0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
36a00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
36a10 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 ror() or.** sqli
36a20 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
36a30 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 16() is non-nega
36a40 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 tive then SQLite
36a50 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 takes that many
36a60 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 .** bytes (not c
36a70 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 haracters) from
36a80 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
36a90 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d r as the error m
36aa0 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 essage..** ^The
36ab0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
36ac0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 rror() and sqlit
36ad0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
36ae0 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6().** routines
36af0 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 make a private c
36b00 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 opy of the error
36b10 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 message text be
36b20 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 fore.** they ret
36b30 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 urn. Hence, the
36b40 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f calling functio
36b50 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 n can deallocate
36b60 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 or.** modify th
36b70 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 e text after the
36b80 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 y return without
36b90 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 harm..** ^The s
36ba0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
36bb0 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 ror_code() funct
36bc0 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 ion changes the
36bd0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 error code.** re
36be0 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 turned by SQLite
36bf0 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 as a result of
36c00 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 an error in a fu
36c10 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 nction. ^By def
36c20 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 ault,.** the err
36c30 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 or code is SQLIT
36c40 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 E_ERROR. ^A sub
36c50 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 sequent call to
36c60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
36c70 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c rror().** or sql
36c80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
36c90 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 r16() resets the
36ca0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 error code to S
36cb0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a QLITE_ERROR..**.
36cc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
36cd0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f result_error_too
36ce0 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 big() interface
36cf0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f causes SQLite to
36d00 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 throw an.** err
36d10 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 or indicating th
36d20 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 at a string or B
36d30 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 LOB is too long
36d40 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a to represent..**
36d50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
36d60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f _result_error_no
36d70 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 mem() interface
36d80 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f causes SQLite to
36d90 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 throw an.** err
36da0 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 or indicating th
36db0 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f at a memory allo
36dc0 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a cation failed..*
36dd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
36de0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 3_result_int() i
36df0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
36e00 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a e return value.*
36e10 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 * of the applica
36e20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
36e30 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 ction to be the
36e40 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 32-bit signed in
36e50 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 teger.** value g
36e60 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 iven in the 2nd
36e70 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 argument..** ^Th
36e80 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
36e90 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 _int64() interfa
36ea0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 ce sets the retu
36eb0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 rn value.** of t
36ec0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
36ed0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
36ee0 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 to be the 64-bit
36ef0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
36f00 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 ** value given i
36f10 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 n the 2nd argume
36f20 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 nt..**.** ^The s
36f30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 qlite3_result_nu
36f40 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ll() interface s
36f50 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 ets the return v
36f60 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 alue.** of the a
36f70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
36f80 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
36f90 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 e NULL..**.** ^T
36fa0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
36fb0 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 t_text(), sqlite
36fc0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 3_result_text16(
36fd0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 ),.** sqlite3_re
36fe0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c sult_text16le(),
36ff0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 and sqlite3_res
37000 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 ult_text16be() i
37010 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 nterfaces.** set
37020 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
37030 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 e of the applica
37040 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
37050 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 ction to be.** a
37060 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 text string whi
37070 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 ch is represente
37080 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d d as UTF-8, UTF-
37090 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 16 native byte o
370a0 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 rder,.** UTF-16
370b0 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f little endian, o
370c0 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 r UTF-16 big end
370d0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c ian, respectivel
370e0 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 y..** ^The sqlit
370f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34 e3_result_text64
37100 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
37110 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
37120 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c ue of an.** appl
37130 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
37140 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
37150 20 74 65 78 74 20 73 74 72 69 6e 67 20 69 6e 20 text string in
37160 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73 an encoding.** s
37170 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
37180 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73 74 29 fifth (and last)
37190 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 parameter, whic
371a0 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a h must be one.**
371b0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 of [SQLITE_UTF8
371c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 ], [SQLITE_UTF16
371d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 ], [SQLITE_UTF16
371e0 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f BE], or [SQLITE_
371f0 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 UTF16LE]..** ^SQ
37200 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 Lite takes the t
37210 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 ext result from
37220 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
37230 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 from.** the 2nd
37240 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 parameter of the
37250 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37260 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
37270 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 ..** ^If the 3rd
37280 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
37290 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
372a0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
372b0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 s.** is negative
372c0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 , then SQLite ta
372d0 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 kes result text
372e0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 from the 2nd par
372f0 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 ameter.** throug
37300 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f h the first zero
37310 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e character..** ^
37320 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d If the 3rd param
37330 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
37340 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
37350 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 interfaces.** i
37360 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
37370 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 then as many byt
37380 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 es (not characte
37390 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a rs) of the text.
373a0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 ** pointed to by
373b0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
373c0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 er are taken as
373d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
373e0 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 defined.** funct
373f0 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 ion result. If
37400 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
37410 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 r is non-negativ
37420 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 e, then it.** mu
37430 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f st be the byte o
37440 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 ffset into the s
37450 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 tring where the
37460 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 NUL terminator w
37470 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 ould.** appear i
37480 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 f the string whe
37490 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 re NUL terminate
374a0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 d. If any NUL c
374b0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a haracters occur.
374c0 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 ** in the string
374d0 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 at a byte offse
374e0 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 t that is less t
374f0 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 han the value of
37500 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 the 3rd.** para
37510 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 meter, then the
37520 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
37530 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d will contain em
37540 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 bedded NULs and
37550 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 the.** result of
37560 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 expressions ope
37570 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 rating on string
37580 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 s with embedded
37590 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 NULs is undefine
375a0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 d..** ^If the 4t
375b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
375c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
375d0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
375e0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 es.** or sqlite3
375f0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 _result_blob is
37600 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
37610 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
37620 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 calls that.** fu
37630 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 nction as the de
37640 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 structor on the
37650 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 text or BLOB res
37660 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a ult when it has.
37670 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e ** finished usin
37680 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a g that result..*
37690 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 * ^If the 4th pa
376a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
376b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
376c0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f xt* interfaces o
376d0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f r to.** sqlite3_
376e0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
376f0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
37700 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ant SQLITE_STATI
37710 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a C, then SQLite.*
37720 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 * assumes that t
37730 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 he text or BLOB
37740 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e result is in con
37750 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 stant space and
37760 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 does not.** copy
37770 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
37780 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f the parameter no
37790 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 r call a destruc
377a0 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 tor on the conte
377b0 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 nt.** when it ha
377c0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 s finished using
377d0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a that result..**
377e0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 ^If the 4th par
377f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
37800 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
37810 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
37820 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
37830 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 lt_blob is the s
37840 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 pecial constant
37850 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
37860 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 .** then SQLite
37870 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
37880 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 the result into
37890 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 space obtained f
378a0 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c rom.** from [sql
378b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 ite3_malloc()] b
378c0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 efore it returns
378d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
378e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
378f0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 e() interface se
37900 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 ts the result of
37910 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
37920 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
37930 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 tion to be a cop
37940 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 y of the.** [unp
37950 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
37960 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 _value] object s
37970 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
37980 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 2nd parameter.
37990 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ^The.** sqlite3_
379a0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 result_value() i
379b0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 nterface makes a
379c0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 copy of the [sq
379d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 lite3_value].**
379e0 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c so that the [sql
379f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 ite3_value] spec
37a00 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 ified in the par
37a10 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 ameter may chang
37a20 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c e or.** be deall
37a30 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c ocated after sql
37a40 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
37a50 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 e() returns with
37a60 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 out harm..** ^A
37a70 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
37a80 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
37a90 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 may always be u
37aa0 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 sed where an.**
37ab0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
37ac0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
37ad0 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 ct is required,
37ae0 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e so either.** kin
37af0 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 d of [sqlite3_va
37b00 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 lue] object can
37b10 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 be used with thi
37b20 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a s interface..**.
37b30 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 ** If these rout
37b40 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
37b50 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 from within the
37b60 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
37b70 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 .** than the one
37b80 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
37b90 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
37ba0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 ned function tha
37bb0 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 t received.** th
37bc0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 e [sqlite3_conte
37bd0 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 xt] pointer, the
37be0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
37bf0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 efined..*/.void
37c00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
37c10 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 lob(sqlite3_cont
37c20 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
37c30 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 *, int, void(*)(
37c40 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 void*));.void sq
37c50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
37c60 62 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 b64(sqlite3_cont
37c70 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ext*,const void*
37c80 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
37c90 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c sql
37ca0 69 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64 ite3_uint64,void
37cb0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
37cc0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
37cd0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
37ce0 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 context*, double
37cf0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
37d00 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c result_error(sql
37d10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
37d20 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 onst char*, int)
37d30 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
37d40 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 esult_error16(sq
37d50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
37d60 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
37d70 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
37d80 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f result_error_too
37d90 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 big(sqlite3_cont
37da0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 ext*);.void sqli
37db0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
37dc0 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 _nomem(sqlite3_c
37dd0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 ontext*);.void s
37de0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
37df0 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 ror_code(sqlite3
37e00 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b _context*, int);
37e10 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
37e20 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 sult_int(sqlite3
37e30 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b _context*, int);
37e40 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
37e50 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 sult_int64(sqlit
37e60 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c e3_context*, sql
37e70 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 ite3_int64);.voi
37e80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
37e90 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f _null(sqlite3_co
37ea0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 ntext*);.void sq
37eb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
37ec0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
37ed0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c t*, const char*,
37ee0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
37ef0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 id*));.void sqli
37f00 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 te3_result_text6
37f10 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 4(sqlite3_contex
37f20 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c t*, const char*,
37f30 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a sqlite3_uint64,.
37f40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
37f50 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 void(
37f60 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 *)(void*), unsig
37f70 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e ned char encodin
37f80 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 g);.void sqlite3
37f90 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 _result_text16(s
37fa0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
37fb0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
37fc0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
37fd0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
37fe0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 _result_text16le
37ff0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
38000 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
38010 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 int,void(*)(void
38020 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 *));.void sqlite
38030 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 3_result_text16b
38040 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
38050 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
38060 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 int,void(*)(voi
38070 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 d*));.void sqlit
38080 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
38090 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
380a0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a , sqlite3_value*
380b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
380c0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 result_zeroblob(
380d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
380e0 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 , int n);.int sq
380f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 lite3_result_zer
38100 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f oblob64(sqlite3_
38110 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 context*, sqlite
38120 33 5f 75 69 6e 74 36 34 20 6e 29 3b 0a 0a 0a 2f 3_uint64 n);.../
38130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
38140 65 74 74 69 6e 67 20 54 68 65 20 53 75 62 74 79 etting The Subty
38150 70 65 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e pe Of An SQL Fun
38160 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a ction.** METHOD:
38170 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
38180 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
38190 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70 e3_result_subtyp
381a0 65 28 43 2c 54 29 20 66 75 6e 63 74 69 6f 6e 20 e(C,T) function
381b0 63 61 75 73 65 73 20 74 68 65 20 73 75 62 74 79 causes the subty
381c0 70 65 20 6f 66 0a 2a 2a 20 74 68 65 20 72 65 73 pe of.** the res
381d0 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 5b 61 70 ult from the [ap
381e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
381f0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 d SQL function]
38200 77 69 74 68 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 with .** [sqlite
38210 33 5f 63 6f 6e 74 65 78 74 5d 20 43 20 74 6f 20 3_context] C to
38220 62 65 20 74 68 65 20 76 61 6c 75 65 20 54 2e 20 be the value T.
38230 20 4f 6e 6c 79 20 74 68 65 20 6c 6f 77 65 72 20 Only the lower
38240 38 20 62 69 74 73 20 0a 2a 2a 20 6f 66 20 74 68 8 bits .** of th
38250 65 20 73 75 62 74 79 70 65 20 54 20 61 72 65 20 e subtype T are
38260 70 72 65 73 65 72 76 65 64 20 69 6e 20 63 75 72 preserved in cur
38270 72 65 6e 74 20 76 65 72 73 69 6f 6e 73 20 6f 66 rent versions of
38280 20 53 51 4c 69 74 65 3b 0a 2a 2a 20 68 69 67 68 SQLite;.** high
38290 65 72 20 6f 72 64 65 72 20 62 69 74 73 20 61 72 er order bits ar
382a0 65 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 e discarded..**
382b0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 73 75 The number of su
382c0 62 74 79 70 65 20 62 79 74 65 73 20 70 72 65 73 btype bytes pres
382d0 65 72 76 65 64 20 62 79 20 53 51 4c 69 74 65 20 erved by SQLite
382e0 6d 69 67 68 74 20 69 6e 63 72 65 61 73 65 0a 2a might increase.*
382f0 2a 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 * in future rele
38300 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
38310 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f */.void sqlite3_
38320 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65 28 73 result_subtype(s
38330 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
38340 75 6e 73 69 67 6e 65 64 20 69 6e 74 29 3b 0a 0a unsigned int);..
38350 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
38360 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 Define New Colla
38370 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a ting Sequences.*
38380 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
38390 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 3.**.** ^These f
383a0 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 unctions add, re
383b0 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 move, or modify
383c0 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 a [collation] as
383d0 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 sociated.** with
383e0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
383f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 onnection] speci
38400 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 fied as the firs
38410 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a t argument..**.*
38420 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 * ^The name of t
38430 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 he collation is
38440 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a a UTF-8 string.*
38450 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 * for sqlite3_cr
38460 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 eate_collation()
38470 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 and sqlite3_cre
38480 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
38490 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d ().** and a UTF-
384a0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 16 string in nat
384b0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 ive byte order f
384c0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 or sqlite3_creat
384d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e e_collation16().
384e0 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e .** ^Collation n
384f0 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 ames that compar
38500 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e e equal accordin
38510 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 g to [sqlite3_st
38520 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a rnicmp()] are.**
38530 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 considered to b
38540 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e e the same name.
38550 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 .**.** ^(The thi
38560 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 rd argument (eTe
38570 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f xtRep) must be o
38580 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 ne of the consta
38590 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 nts:.** <ul>.**
385a0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 <li> [SQLITE_UTF
385b0 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 8],.** <li> [SQL
385c0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a ITE_UTF16LE],.**
385d0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 <li> [SQLITE_UT
385e0 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 F16BE],.** <li>
385f0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 [SQLITE_UTF16],
38600 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 or.** <li> [SQLI
38610 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
38620 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a ]..** </ul>)^.**
38630 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 ^The eTextRep a
38640 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e rgument determin
38650 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 es the encoding
38660 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 of strings passe
38670 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c d.** to the coll
38680 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 ating function c
38690 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 allback, xCallba
386a0 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c ck..** ^The [SQL
386b0 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b ITE_UTF16] and [
386c0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
386d0 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 GNED] values for
386e0 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 eTextRep.** for
386f0 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 ce strings to be
38700 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 UTF16 with nati
38710 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
38720 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 * ^The [SQLITE_U
38730 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 TF16_ALIGNED] va
38740 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 lue for eTextRep
38750 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 forces strings
38760 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 to begin.** on a
38770 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 n even byte addr
38780 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ess..**.** ^The
38790 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c fourth argument,
387a0 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 pArg, is an app
387b0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
387c0 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 inter that is pa
387d0 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 ssed.** through
387e0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
387f0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c ument to the col
38800 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
38810 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 callback..**.**
38820 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d ^The fifth argum
38830 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 ent, xCallback,
38840 69 73