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 69 6e 73 er, and thus ins
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 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 insure 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 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 _LOCKED_SHAREDCA
55b0: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 CHE (SQLITE
55c0: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 _LOCKED | (1<<8
55d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
55e0: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 E_BUSY_RECOVERY
55f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5600: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c E_BUSY | (1<<
5610: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5620: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 TE_BUSY_SNAPSHOT
5630: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
5640: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c TE_BUSY | (2<
5650: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5660: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 ITE_CANTOPEN_NOT
5670: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c EMPDIR (SQL
5680: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
5690: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
56a0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 QLITE_CANTOPEN_I
56b0: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53 SDIR (S
56c0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c QLITE_CANTOPEN |
56d0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
56e0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
56f0: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 _FULLPATH
5700: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e (SQLITE_CANTOPEN
5710: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 | (3<<8)).#defi
5720: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 ne SQLITE_CANTOP
5730: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 EN_CONVPATH
5740: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 (SQLITE_CANTOP
5750: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 EN | (4<<8)).#de
5760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 fine SQLITE_CORR
5770: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 UPT_VTAB
5780: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 (SQLITE_CORR
5790: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 UPT | (1<<8)).#d
57a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
57b0: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 DONLY_RECOVERY
57c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
57d0: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a DONLY | (1<<8)).
57e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
57f0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b EADONLY_CANTLOCK
5800: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 (SQLITE_R
5810: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 EADONLY | (2<<8)
5820: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5830: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 _READONLY_ROLLBA
5840: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 CK (SQLITE
5850: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c _READONLY | (3<<
5860: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5870: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f TE_READONLY_DBMO
5880: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 VED (SQLI
5890: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 TE_READONLY | (4
58a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
58b0: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 LITE_ABORT_ROLLB
58c0: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 ACK (SQ
58d0: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c LITE_ABORT | (2<
58e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
58f0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 ITE_CONSTRAINT_C
5900: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c HECK (SQL
5910: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5920: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
5930: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5940: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 NT_COMMITHOOK
5950: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5960: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 NT | (2<<8)).#de
5970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5980: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 TRAINT_FOREIGNKE
5990: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 Y (SQLITE_CONS
59a0: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 TRAINT | (3<<8))
59b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
59c0: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 CONSTRAINT_FUNCT
59d0: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f ION (SQLITE_
59e0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c CONSTRAINT | (4<
59f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5a00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e ITE_CONSTRAINT_N
5a10: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c OTNULL (SQL
5a20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5a30: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (5<<8)).#define
5a40: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5a50: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 NT_PRIMARYKEY
5a60: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5a70: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 NT | (6<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5a90: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 TRAINT_TRIGGER
5aa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
5ab0: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 TRAINT | (7<<8))
5ac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5ad0: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 CONSTRAINT_UNIQU
5ae0: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f E (SQLITE_
5af0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c CONSTRAINT | (8<
5b00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5b10: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 ITE_CONSTRAINT_V
5b20: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c TAB (SQL
5b30: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5b40: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (9<<8)).#define
5b50: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5b60: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 NT_ROWID
5b70: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5b80: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 NT |(10<<8)).#de
5b90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 fine SQLITE_NOTI
5ba0: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 CE_RECOVER_WAL
5bb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 (SQLITE_NOTI
5bc0: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 CE | (1<<8)).#de
5bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 fine SQLITE_NOTI
5be0: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 CE_RECOVER_ROLLB
5bf0: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 ACK (SQLITE_NOTI
5c00: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 CE | (2<<8)).#de
5c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e fine SQLITE_WARN
5c20: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 ING_AUTOINDEX
5c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e (SQLITE_WARN
5c40: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 ING | (1<<8)).#d
5c50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 efine SQLITE_AUT
5c60: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 H_USER
5c70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 (SQLITE_AUT
5c80: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a H | (1<<8))../*.
5c90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 ** CAPI3REF: Fla
5ca0: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e gs For File Open
5cb0: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a Operations.**.*
5cc0: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 * These bit valu
5cd0: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 es are intended
5ce0: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a for use in the.*
5cf0: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 * 3rd parameter
5d00: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
5d10: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 open_v2()] inter
5d20: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 face and.** in t
5d30: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
5d40: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
5d50: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 _vfs.xOpen] meth
5d60: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 od..*/.#define S
5d70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
5d80: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 NLY 0x00
5d90: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 000001 /* Ok fo
5da0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5db0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5dc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
5dd0: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 RITE 0x00
5de0: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 000002 /* Ok fo
5df0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5e00: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5e10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
5e20: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 E 0x00
5e30: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 000004 /* Ok fo
5e40: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5e50: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5e60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
5e70: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 EONCLOSE 0x00
5e80: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 000008 /* VFS o
5e90: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5ea0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
5eb0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 SIVE 0x00
5ec0: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 000010 /* VFS o
5ed0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5ee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 QLITE_OPEN_AUTOP
5ef0: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 ROXY 0x00
5f00: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 000020 /* 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 55 52 49 20 20 QLITE_OPEN_URI
5f30: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
5f40: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 000040 /* Ok fo
5f50: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5f60: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5f70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 QLITE_OPEN_MEMOR
5f80: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 Y 0x00
5f90: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 000080 /* Ok fo
5fa0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5fb0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5fc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
5fd0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
5fe0: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 000100 /* VFS o
5ff0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
6000: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
6010: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
6020: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 000200 /* VFS o
6030: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 QLITE_OPEN_TRANS
6050: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 IENT_DB 0x00
6060: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 000400 /* 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 4d 41 49 4e 5f QLITE_OPEN_MAIN_
6090: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
60a0: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 000800 /* 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 45 4d 50 5f QLITE_OPEN_TEMP_
60d0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
60e0: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 001000 /* 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 53 55 42 4a 4f QLITE_OPEN_SUBJO
6110: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 URNAL 0x00
6120: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 002000 /* 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 4d 41 53 54 45 QLITE_OPEN_MASTE
6150: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 R_JOURNAL 0x00
6160: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 004000 /* 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 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
6190: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 EX 0x00
61a0: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 008000 /* Ok fo
61b0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
61c0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
61d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
61e0: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 UTEX 0x00
61f0: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 010000 /* Ok fo
6200: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
6210: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
6220: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
6230: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 DCACHE 0x00
6240: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 020000 /* Ok fo
6250: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
6260: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
6270: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
6280: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 TECACHE 0x00
6290: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 040000 /* Ok fo
62a0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
62b0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
62c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 QLITE_OPEN_WAL
62d0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
62e0: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 080000 /* VFS o
62f0: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 nly */../* Reser
6300: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 ved:
6310: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6320: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 0F00000 */../*.*
6330: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 * CAPI3REF: Devi
6340: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 ce Characteristi
6350: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 cs.**.** The xDe
6360: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
6370: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 ics method of th
6380: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
6390: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 thods].** object
63a0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 returns an inte
63b0: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 ger which is a v
63c0: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a ector of these.*
63d0: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 * bit values exp
63e0: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 ressing I/O char
63f0: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 acteristics of t
6400: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a he mass storage.
6410: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 ** device that h
6420: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 olds the file th
6430: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
6440: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 io_methods].** r
6450: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 efers to..**.**
6460: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
6470: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
6480: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
6490: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
64a0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
64b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
64c0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
64d0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
64e0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
64f0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
6500: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
6510: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
6520: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
6530: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
6540: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
6550: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
6560: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
6570: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
6580: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
6590: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
65a0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
65b0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
65c0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
65d0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
65e0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
65f0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
6600: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
6610: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
6620: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
6630: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
6640: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
6650: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
6660: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
6670: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
6680: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
6690: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 ite(). The SQLI
66a0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
66b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f FE_OVERWRITE pro
66c0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
66d0: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 .** after reboot
66e0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 following a cra
66f0: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 sh or power loss
6700: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 , the only bytes
6710: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 in a.** file th
6720: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 at were written
6730: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 at the applicati
6740: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 on level might h
6750: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 ave changed.** a
6760: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 nd that adjacent
6770: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 bytes, even byt
6780: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 es within the sa
6790: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a me sector are.**
67a0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 guaranteed to b
67b0: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 e unchanged. Th
67c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 e SQLITE_IOCAP_U
67d0: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f NDELETABLE_WHEN_
67e0: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 OPEN.** flag ind
67f0: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c icate that a fil
6800: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 e cannot be dele
6810: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 ted when open.
6820: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f The.** SQLITE_IO
6830: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c CAP_IMMUTABLE fl
6840: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 ag indicates tha
6850: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e t the file is on
6860: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 .** read-only me
6870: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 dia and cannot b
6880: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 e changed even b
6890: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 y processes with
68a0: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 .** elevated pri
68b0: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 vileges..*/.#def
68c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
68d0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 _ATOMIC
68e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
68f0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 01.#define SQLIT
6900: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
6910: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 2 0
6920: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e x00000002.#defin
6930: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6940: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 TOMIC1K
6950: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
6960: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6970: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 IOCAP_ATOMIC2K
6980: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6990: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 0000008.#define
69a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
69b0: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 MIC4K
69c0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 0x00000010.#
69d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
69e0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 CAP_ATOMIC8K
69f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6a00: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 00020.#define SQ
6a10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6a20: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 C16K
6a30: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 0x00000040.#de
6a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6a50: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 P_ATOMIC32K
6a60: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6a70: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 080.#define SQLI
6a80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 TE_IOCAP_ATOMIC6
6a90: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 4K
6aa0: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 0x00000100.#defi
6ab0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6ac0: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 SAFE_APPEND
6ad0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 0x0000020
6ae0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
6af0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
6b00: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 L 0x
6b10: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 00000400.#define
6b20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e SQLITE_IOCAP_UN
6b30: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f DELETABLE_WHEN_O
6b40: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a PEN 0x00000800.
6b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6b60: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f OCAP_POWERSAFE_O
6b70: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 VERWRITE 0x00
6b80: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 001000.#define S
6b90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 QLITE_IOCAP_IMMU
6ba0: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 TABLE
6bb0: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 0x00002000../
6bc0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
6bd0: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 ile Locking Leve
6be0: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 ls.**.** SQLite
6bf0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 uses one of thes
6c00: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
6c10: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a as the second.*
6c20: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 * argument to ca
6c30: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 lls it makes to
6c40: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 the xLock() and
6c50: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 xUnlock() method
6c60: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 s.** of an [sqli
6c70: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
6c80: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 object..*/.#defi
6c90: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e ne SQLITE_LOCK_N
6ca0: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 ONE 0.#
6cb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
6cc0: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 CK_SHARED
6cd0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
6ce0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 E_LOCK_RESERVED
6cf0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
6d00: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
6d10: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 NG 3.#defi
6d20: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 ne SQLITE_LOCK_E
6d30: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a XCLUSIVE 4..
6d40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
6d50: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 Synchronization
6d60: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a Type Flags.**.**
6d70: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 When SQLite inv
6d80: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 okes the xSync()
6d90: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a method of an.**
6da0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
6db0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 hods] object it
6dc0: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 uses a combinati
6dd0: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 on of.** these i
6de0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 nteger values as
6df0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
6e00: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e ment..**.** When
6e10: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 the SQLITE_SYNC
6e20: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 _DATAONLY flag i
6e30: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 s used, it means
6e40: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e that the.** syn
6e50: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 c operation only
6e60: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 needs to flush
6e70: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f data to mass sto
6e80: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 rage. Inode.**
6e90: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 information need
6ea0: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e not be flushed.
6eb0: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f If the lower fo
6ec0: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 ur bits of the f
6ed0: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c lag.** equal SQL
6ee0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c ITE_SYNC_NORMAL,
6ef0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 that means to u
6f00: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 se normal fsync(
6f10: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 ) semantics..**
6f20: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 If the lower fou
6f30: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c r bits equal SQL
6f40: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 ITE_SYNC_FULL, t
6f50: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 hat means.** to
6f60: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 use Mac OS X sty
6f70: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 le fullsync inst
6f80: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a ead of fsync()..
6f90: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e **.** Do not con
6fa0: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f fuse the SQLITE_
6fb0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
6fc0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
6fd0: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 flags.** with t
6fe0: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 he [PRAGMA synch
6ff0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 ronous]=NORMAL a
7000: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 nd [PRAGMA synch
7010: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 ronous]=FULL.**
7020: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b settings. The [
7030: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 synchronous prag
7040: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 ma] determines w
7050: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 hen calls to the
7060: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 .** xSync VFS me
7070: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 thod occur and a
7080: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 pplies uniformly
7090: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 across all plat
70a0: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 forms..** The SQ
70b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
70c0: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 and SQLITE_SYNC
70d0: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 _FULL flags dete
70e0: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 rmine how.** ene
70f0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f rgetic or rigoro
7100: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 us or forceful t
7110: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f he sync operatio
7120: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e ns are and.** on
7130: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 ly make a differ
7140: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 ence on Mac OSX
7150: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 for the default
7160: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 SQLite code..**
7170: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 (Third-party VFS
7180: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
7190: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 might also make
71a0: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e the distinction
71b0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 .** between SQLI
71c0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 TE_SYNC_NORMAL a
71d0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 nd SQLITE_SYNC_F
71e0: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 ULL, but among t
71f0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 he.** operating
7200: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 systems natively
7210: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 supported by SQ
7220: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f Lite, only Mac O
7230: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 SX.** cares abou
7240: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 t the difference
7250: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 .).*/.#define SQ
7260: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
7270: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 0x00002.
7280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
7290: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 YNC_FULL
72a0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 0x00003.#defin
72b0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
72c0: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 TAONLY 0x00
72d0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 010../*.** CAPI3
72e0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
72f0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 e Open File Hand
7300: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c le.**.** An [sql
7310: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
7320: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 t represents an
7330: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 open file in the
7340: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 .** [sqlite3_vf
7350: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 s | OS interface
7360: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 layer]. Indivi
7370: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 dual OS interfac
7380: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
7390: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e ions will.** wan
73a0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 t to subclass th
73b0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 is object by app
73c0: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 ending additiona
73d0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 l fields.** for
73e0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 their own use.
73f0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 The pMethods ent
7400: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ry is a pointer
7410: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 to an.** [sqlite
7420: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
7430: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
7440: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 s methods for pe
7450: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 rforming.** I/O
7460: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 operations on th
7470: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a e open file..*/.
7480: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
7490: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 qlite3_file sqli
74a0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 te3_file;.struct
74b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a sqlite3_file {.
74c0: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 const struct s
74d0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
74e0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a s *pMethods; /*
74f0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 Methods for an
7500: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a open file */.};.
7510: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
7520: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 OS Interface Fi
7530: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f le Virtual Metho
7540: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 ds Object.**.**
7550: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 Every file opene
7560: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
7570: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 3_vfs.xOpen] met
7580: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e hod populates an
7590: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
75a0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d e] object (or, m
75b0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 ore commonly, a
75c0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a subclass of the.
75d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
75e0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 ] object) with a
75f0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
7600: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
7610: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 object..** This
7620: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
7630: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 he methods used
7640: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
7650: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a us operations.**
7660: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 against the ope
7670: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 n file represent
7680: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
7690: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e e3_file] object.
76a0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 .**.** If the [s
76b0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
76c0: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 ] method sets th
76d0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
76e0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 Methods element
76f0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c .** to a non-NUL
7700: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
7710: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d the sqlite3_io_m
7720: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 ethods.xClose me
7730: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 thod.** may be i
7740: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 nvoked even if t
7750: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
7760: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 xOpen] reported
7770: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 that it failed.
7780: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 The.** only way
7790: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 to prevent a ca
77a0: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c ll to xClose fol
77b0: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 lowing a failed
77c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
77d0: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 en].** is for th
77e0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
77f0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 Open] to set the
7800: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
7810: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a ethods element.*
7820: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a * to NULL..**.**
7830: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d The flags argum
7840: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 ent to xSync may
7850: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 be one of [SQLI
7860: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 TE_SYNC_NORMAL]
7870: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 or.** [SQLITE_SY
7880: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 NC_FULL]. The f
7890: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 irst choice is t
78a0: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 he normal fsync(
78b0: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 )..** The second
78c0: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 choice is a Mac
78d0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c OS X style full
78e0: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 sync. The [SQLI
78f0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
7900: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 ].** flag may be
7910: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 ORed in to indi
7920: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 cate that only t
7930: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 he data of the f
7940: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 ile.** and not i
7950: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 ts inode needs t
7960: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a o be synced..**.
7970: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 ** The integer v
7980: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 alues to xLock()
7990: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 and xUnlock() a
79a0: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c re one of.** <ul
79b0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
79c0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a E_LOCK_NONE],.**
79d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
79e0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c CK_SHARED],.** <
79f0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
7a00: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c _RESERVED],.** <
7a10: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
7a20: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a _PENDING], or.**
7a30: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
7a40: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a CK_EXCLUSIVE]..*
7a50: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b * </ul>.** xLock
7a60: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 () increases the
7a70: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 lock. xUnlock()
7a80: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c decreases the l
7a90: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 ock..** The xChe
7aa0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 ckReservedLock()
7ab0: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 method checks w
7ac0: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 hether any datab
7ad0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a ase connection,.
7ae0: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 ** either in thi
7af0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 s process or in
7b00: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 some other proce
7b10: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 ss, is holding a
7b20: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 RESERVED,.** PE
7b30: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 NDING, or EXCLUS
7b40: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 IVE lock on the
7b50: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e file. It return
7b60: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 s true.** if suc
7b70: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 h a lock exists
7b80: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 and false otherw
7b90: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ise..**.** The x
7ba0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 FileControl() me
7bb0: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 thod is a generi
7bc0: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 c interface that
7bd0: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a allows custom.*
7be0: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 * VFS implementa
7bf0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c tions to directl
7c00: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 y control an ope
7c10: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 n file using the
7c20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
7c30: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 e_control()] int
7c40: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 erface. The sec
7c50: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e ond "op" argumen
7c60: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 t is an.** integ
7c70: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 er opcode. The
7c80: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
7c90: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e s a generic poin
7ca0: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a ter intended to.
7cb0: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 ** point to a st
7cc0: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 ructure that may
7cd0: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e contain argumen
7ce0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 ts or space in w
7cf0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 hich to.** write
7d00: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 return values.
7d10: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 Potential uses
7d20: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c for xFileControl
7d30: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 () might be.** f
7d40: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 unctions to enab
7d50: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b le blocking lock
7d60: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c s with timeouts,
7d70: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a to change the.*
7d80: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 * locking strate
7d90: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 gy (for example
7da0: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 to use dot-file
7db0: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 locks), to inqui
7dc0: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 re.** about the
7dd0: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b status of a lock
7de0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 , or to break st
7df0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 ale locks. The
7e00: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 SQLite.** core r
7e10: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f eserves all opco
7e20: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 des less than 10
7e30: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 0 for its own us
7e40: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f e..** A [file co
7e50: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 ntrol opcodes |
7e60: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d list of opcodes]
7e70: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 less than 100 i
7e80: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 s available..**
7e90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
7ea0: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f t define a custo
7eb0: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d m xFileControl m
7ec0: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 ethod should use
7ed0: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 opcodes.** grea
7ee0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 ter than 100 to
7ef0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e avoid conflicts.
7f00: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 VFS implementa
7f10: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 tions should.**
7f20: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e return [SQLITE_N
7f30: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c OTFOUND] for fil
7f40: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 e control opcode
7f50: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e s that they do n
7f60: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e ot.** recognize.
7f70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 .**.** The xSect
7f80: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 orSize() method
7f90: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 returns the sect
7fa0: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a or size of the.*
7fb0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e * device that un
7fc0: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 derlies the file
7fd0: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 . The sector si
7fe0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e ze is the.** min
7ff0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 imum write that
8000: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 can be performed
8010: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 without disturb
8020: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 ing.** other byt
8030: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 es in the file.
8040: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 The xDeviceChar
8050: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a acteristics().**
8060: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
8070: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 a bit vector des
8080: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 cribing behavior
8090: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 s of the.** unde
80a0: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a rlying device:.*
80b0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
80c0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
80d0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 ATOMIC].** <li>
80e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
80f0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e OMIC512].** <li>
8100: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
8110: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC1K].** <li>
8120: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
8130: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC2K].** <li>
8140: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
8150: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC4K].** <li>
8160: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
8170: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC8K].** <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 36 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC16K].** <li
81a0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
81b0: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c ATOMIC32K].** <l
81c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
81d0: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c _ATOMIC64K].** <
81e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
81f0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a P_SAFE_APPEND].*
8200: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
8210: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d OCAP_SEQUENTIAL]
8220: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
8230: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
8240: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
8250: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
8260: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
8270: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
8280: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
8290: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
82a0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
82b0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
82c0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
82d0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
82e0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
82f0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
8300: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
8310: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
8320: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
8330: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
8340: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
8350: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
8360: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
8370: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
8380: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
8390: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
83a0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
83b0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
83c0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
83d0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
83e0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
83f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
8400: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
8410: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
8420: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
8430: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
8440: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
8450: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
8460: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ite()..**.** If
8470: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 xRead() returns
8480: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
8490: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 RT_READ it must
84a0: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 also fill.** in
84b0: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 the unread porti
84c0: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 ons of the buffe
84d0: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 r with zeros. A
84e0: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 VFS that.** fai
84f0: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 ls to zero-fill
8500: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 short reads migh
8510: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 t seem to work.
8520: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 However,.** fai
8530: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c lure to zero-fil
8540: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 l short reads wi
8550: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 ll eventually le
8560: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 ad to.** databas
8570: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f e corruption..*/
8580: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
8590: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
85a0: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ds sqlite3_io_me
85b0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
85c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
85d0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f {. int iVersio
85e0: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 n;. int (*xClos
85f0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
8600: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 );. int (*xRead
8610: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8620: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 void*, int iAmt
8630: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
8640: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a iOfst);. int (*
8650: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f xWrite)(sqlite3_
8660: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 file*, const voi
8670: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 d*, int iAmt, sq
8680: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 lite3_int64 iOfs
8690: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 t);. int (*xTru
86a0: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 ncate)(sqlite3_f
86b0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
86c0: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 t64 size);. int
86d0: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 (*xSync)(sqlite
86e0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 3_file*, int fla
86f0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 gs);. int (*xFi
8700: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f leSize)(sqlite3_
8710: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
8720: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 nt64 *pSize);.
8730: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c int (*xLock)(sql
8740: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 ite3_file*, int)
8750: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 ;. int (*xUnloc
8760: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
8770: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a , int);. int (*
8780: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f xCheckReservedLo
8790: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
87a0: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 *, int *pResOut)
87b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 ;. int (*xFileC
87c0: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f ontrol)(sqlite3_
87d0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 file*, int op, v
87e0: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e oid *pArg);. in
87f0: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 t (*xSectorSize)
8800: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
8810: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 . int (*xDevice
8820: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 Characteristics)
8830: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
8840: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 . /* Methods ab
8850: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f ove are valid fo
8860: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 r version 1 */.
8870: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 int (*xShmMap)(
8880: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
8890: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a nt iPg, int pgsz
88a0: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 , int, void vola
88b0: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 tile**);. int (
88c0: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 *xShmLock)(sqlit
88d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 e3_file*, int of
88e0: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 fset, int n, int
88f0: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 flags);. void
8900: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 (*xShmBarrier)(s
8910: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
8920: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 int (*xShmUnmap
8930: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8940: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 int deleteFlag)
8950: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 ;. /* Methods a
8960: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 bove are valid f
8970: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a or version 2 */.
8980: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 int (*xFetch)(
8990: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
89a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
89b0: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f st, int iAmt, vo
89c0: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 id **pp);. int
89d0: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 (*xUnfetch)(sqli
89e0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
89f0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 e3_int64 iOfst,
8a00: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d void *p);. /* M
8a10: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
8a20: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 valid for versi
8a30: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 on 3 */. /* Add
8a40: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 itional methods
8a50: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
8a60: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
8a70: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
8a80: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 I3REF: Standard
8a90: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 File Control Opc
8aa0: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 odes.** KEYWORDS
8ab0: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 : {file control
8ac0: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 opcodes} {file c
8ad0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a ontrol opcode}.*
8ae0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 *.** These integ
8af0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 er constants are
8b00: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 opcodes for the
8b10: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
8b20: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b thod.** of the [
8b30: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
8b40: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 ds] object and f
8b50: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f or the [sqlite3_
8b60: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a file_control()].
8b70: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a ** interface..**
8b80: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
8b90: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c [[SQLITE_FCNTL_L
8ba0: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 OCKSTATE]].** Th
8bb0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
8bc0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 LOCKSTATE] opcod
8bd0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 e is used for de
8be0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a bugging. This.*
8bf0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 * opcode causes
8c00: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
8c10: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 method to write
8c20: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 the current sta
8c30: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 te of.** the loc
8c40: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 k (one of [SQLIT
8c50: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 E_LOCK_NONE], [S
8c60: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
8c70: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c D],.** [SQLITE_L
8c80: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b OCK_RESERVED], [
8c90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
8ca0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 ING], or [SQLITE
8cb0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d _LOCK_EXCLUSIVE]
8cc0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 ).** into an int
8cd0: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 eger that the pA
8ce0: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e rg argument poin
8cf0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 ts to. This capa
8d00: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 bility.** is use
8d10: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 d during testing
8d20: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 and is only ava
8d30: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 ilable when the
8d40: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 SQLITE_TEST.** c
8d50: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
8d60: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a on is used..**.*
8d70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
8d80: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d CNTL_SIZE_HINT]]
8d90: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
8da0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d FCNTL_SIZE_HINT]
8db0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
8dc0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 by SQLite to giv
8dd0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 e the VFS.** lay
8de0: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 er a hint of how
8df0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 large the datab
8e00: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 ase file will gr
8e10: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 ow to be during
8e20: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 the.** current t
8e30: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 ransaction. Thi
8e40: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 s hint is not gu
8e50: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 aranteed to be a
8e60: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a ccurate but it.*
8e70: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 * is often close
8e80: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e . The underlyin
8e90: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f g VFS might choo
8ea0: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 se to preallocat
8eb0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 e database.** fi
8ec0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f le space based o
8ed0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f n this hint in o
8ee0: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 rder to help wri
8ef0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 tes to the datab
8f00: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 ase.** file run
8f10: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c faster..**.** <l
8f20: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
8f30: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a _CHUNK_SIZE]].**
8f40: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
8f50: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f TL_CHUNK_SIZE] o
8f60: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
8f70: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 request that th
8f80: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 e VFS.** extends
8f90: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 and truncates t
8fa0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
8fb0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 in chunks of a
8fc0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a size specified.*
8fd0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 * by the user. T
8fe0: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
8ff0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 nt to [sqlite3_f
9000: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 ile_control()] s
9010: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 hould .** point
9020: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 to an integer (t
9030: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e ype int) contain
9040: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e ing the new chun
9050: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a k-size to use.**
9060: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 for the nominat
9070: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c ed database. All
9080: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 ocating database
9090: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c file space in l
90a0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 arge.** chunks (
90b0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d say 1MB at a tim
90c0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 e), may reduce f
90d0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d ile-system fragm
90e0: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 entation and.**
90f0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 improve performa
9100: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 nce on some syst
9110: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ems..**.** <li>[
9120: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 [SQLITE_FCNTL_FI
9130: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 LE_POINTER]].**
9140: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
9150: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 L_FILE_POINTER]
9160: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
9170: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 o obtain a point
9180: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 er.** to the [sq
9190: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
91a0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ct associated wi
91b0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 th a particular
91c0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
91d0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 ection. See the
91e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
91f0: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 ontrol()] docume
9200: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 ntation for.** a
9210: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
9220: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ation..**.** <li
9230: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
9240: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a SYNC_OMITTED]].*
9250: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 * No longer in u
9260: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b se..**.** <li>[[
9270: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e SQLITE_FCNTL_SYN
9280: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 C]].** The [SQLI
9290: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f TE_FCNTL_SYNC] o
92a0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 pcode is generat
92b0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 ed internally by
92c0: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 SQLite and.** s
92d0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 ent to the VFS i
92e0: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 mmediately befor
92f0: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 e the xSync meth
9300: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e od is invoked on
9310: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 a.** database f
9320: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 ile descriptor.
9330: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 Or, if the xSync
9340: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 method is not i
9350: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 nvoked .** becau
9360: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 se the user has
9370: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 configured SQLit
9380: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 e with .** [PRAG
9390: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c MA synchronous |
93a0: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e PRAGMA synchron
93b0: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 ous=OFF] it is i
93c0: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 nvoked in place
93d0: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 .** of the xSync
93e0: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 method. In most
93f0: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e cases, the poin
9400: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 ter argument pas
9410: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 sed with.** this
9420: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 file-control is
9430: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 NULL. However,
9440: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 if the database
9450: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 file is being sy
9460: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 nced.** as part
9470: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 of a multi-datab
9480: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 ase commit, the
9490: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 argument points
94a0: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 to a nul-termina
94b0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f ted.** string co
94c0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 ntaining the tra
94d0: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 nsactions master
94e0: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 -journal file na
94f0: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a me. VFSes that .
9500: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 ** do not need t
9510: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c his signal shoul
9520: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 d silently ignor
9530: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 e this opcode. A
9540: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 pplications .**
9550: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 should not call
9560: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
9570: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 ntrol()] with th
9580: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 is opcode as doi
9590: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 ng so may .** di
95a0: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 srupt the operat
95b0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 ion of the speci
95c0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 alized VFSes tha
95d0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e t do require it.
95e0: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 .**.** <li>[[S
95f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d QLITE_FCNTL_COMM
9600: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a IT_PHASETWO]].**
9610: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
9620: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 TL_COMMIT_PHASET
9630: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 WO] opcode is ge
9640: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c nerated internal
9650: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ly by SQLite.**
9660: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 and sent to the
9670: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e VFS after a tran
9680: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e saction has been
9690: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 committed immed
96a0: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 iately.** but be
96b0: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 fore the databas
96c0: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 e is unlocked. V
96d0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 FSes that do not
96e0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 need this signa
96f0: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 l.** should sile
9700: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 ntly ignore this
9710: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 opcode. Applica
9720: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 tions should not
9730: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 call.** [sqlite
9740: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
9750: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f ] with this opco
9760: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d de as doing so m
9770: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a ay disrupt the .
9780: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 ** operation of
9790: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 the specialized
97a0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 VFSes that do re
97b0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a quire it. .**.*
97c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
97d0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 CNTL_WIN32_AV_RE
97e0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 TRY]].** ^The [S
97f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
9800: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 2_AV_RETRY] opco
9810: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f de is used to co
9820: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 nfigure automati
9830: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 c.** retry count
9840: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 s and intervals
9850: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b for certain disk
9860: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 I/O operations
9870: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f for the.** windo
9880: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 ws [VFS] in orde
9890: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 r to provide rob
98a0: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 ustness in the p
98b0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e resence of.** an
98c0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d ti-virus program
98d0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 s. By default,
98e0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 the windows VFS
98f0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 will retry file
9900: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 read,.** file wr
9910: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 ite, and file de
9920: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 lete operations
9930: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 up to 10 times,
9940: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 with a delay.**
9950: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e of 25 millisecon
9960: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 ds before the fi
9970: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 rst retry and wi
9980: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 th the delay inc
9990: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e reasing.** by an
99a0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d additional 25 m
99b0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 illiseconds with
99c0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 each subsequent
99d0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a retry. This.**
99e0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 opcode allows t
99f0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 hese two values
9a00: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 (10 retries and
9a10: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 25 milliseconds
9a20: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 of delay).** to
9a30: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 be adjusted. Th
9a40: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 e values are cha
9a50: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 nged for all dat
9a60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
9a70: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 s.** within the
9a80: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 same process. T
9a90: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 he argument is a
9aa0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 pointer to an a
9ab0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 rray of two.** i
9ac0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 ntegers where th
9ad0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 e first integer
9ae0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 i the new retry
9af0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 count and the se
9b00: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 cond.** integer
9b10: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 is the delay. I
9b20: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 f either integer
9b30: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
9b40: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a en the setting.*
9b50: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 * is not changed
9b60: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 but instead the
9b70: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 prior value of
9b80: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 that setting is
9b90: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 written.** into
9ba0: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c the array entry,
9bb0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 allowing the cu
9bc0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 rrent retry sett
9bd0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e ings to be.** in
9be0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 terrogated. The
9bf0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 zDbName paramet
9c00: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a er is ignored..*
9c10: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9c20: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f E_FCNTL_PERSIST_
9c30: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 WAL]].** ^The [S
9c40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 QLITE_FCNTL_PERS
9c50: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 IST_WAL] opcode
9c60: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f is used to set o
9c70: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 r query the.** p
9c80: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c ersistent [WAL |
9c90: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 Write Ahead Log
9ca0: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 ] setting. By d
9cb0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 efault, the auxi
9cc0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 liary.** write a
9cd0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 head log and sha
9ce0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 red memory files
9cf0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 used for transa
9d00: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a ction control.**
9d10: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c are automatical
9d20: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 ly deleted when
9d30: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 the latest conne
9d40: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 ction to the dat
9d50: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e abase.** closes.
9d60: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 Setting persis
9d70: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 tent WAL mode ca
9d80: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 uses those files
9d90: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 to persist afte
9da0: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 r.** close. Per
9db0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 sisting the file
9dc0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e s is useful when
9dd0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 other processes
9de0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 that do not.**
9df0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 have write permi
9e00: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 ssion on the dir
9e10: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e ectory containin
9e20: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 g the database f
9e30: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 ile want.** to r
9e40: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 ead the database
9e50: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 file, as the WA
9e60: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d L and shared mem
9e70: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 ory files must e
9e80: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 xist.** in order
9e90: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 for the databas
9ea0: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 e to be readable
9eb0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 . The fourth pa
9ec0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 rameter to.** [s
9ed0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
9ee0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 rol()] for this
9ef0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 opcode should be
9f00: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
9f10: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 integer..** Tha
9f20: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 t integer is 0 t
9f30: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 o disable persis
9f40: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 tent WAL mode or
9f50: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 1 to enable per
9f60: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d sistent.** WAL m
9f70: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 ode. If the int
9f80: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e eger is -1, then
9f90: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 it is overwritt
9fa0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 en with the curr
9fb0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 ent.** WAL persi
9fc0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a stence setting..
9fd0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
9fe0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 TE_FCNTL_POWERSA
9ff0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a FE_OVERWRITE]].*
a000: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
a010: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f CNTL_POWERSAFE_O
a020: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 VERWRITE] opcode
a030: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 is used to set
a040: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 or query the.**
a050: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 persistent "powe
a060: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 rsafe-overwrite"
a070: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 or "PSOW" setti
a080: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 ng. The PSOW se
a090: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 tting.** determi
a0a0: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f nes the [SQLITE_
a0b0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f IOCAP_POWERSAFE_
a0c0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f OVERWRITE] bit o
a0d0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 f the.** xDevice
a0e0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 Characteristics
a0f0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 methods. The fou
a100: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
a110: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
a120: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 e_control()] for
a130: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f this opcode sho
a140: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 uld be a pointer
a150: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a to an integer..
a160: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 ** That integer
a170: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
a180: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 zero-damage mode
a190: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 or 1 to enable
a1a0: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d zero-damage.** m
a1b0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 ode. If the int
a1c0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e eger is -1, then
a1d0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 it is overwritt
a1e0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 en with the curr
a1f0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 ent.** zero-dama
a200: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e ge mode setting.
a210: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
a220: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 ITE_FCNTL_OVERWR
a230: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 ITE]].** ^The [S
a240: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
a250: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 WRITE] opcode is
a260: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 invoked by SQLi
a270: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 te after opening
a280: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e .** a write tran
a290: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 saction to indic
a2a0: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 ate that, unless
a2b0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 it is rolled ba
a2c0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 ck for some.** r
a2d0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 eason, the entir
a2e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
a2f0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 will be overwrit
a300: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 ten by the curre
a310: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 nt .** transacti
a320: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 on. This is used
a330: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 by VACUUM opera
a340: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 tions..**.** <li
a350: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
a360: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 VFSNAME]].** ^Th
a370: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
a380: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 VFSNAME] opcode
a390: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
a3a0: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 btain the names
a3b0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 of.** all [VFSes
a3c0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 ] in the VFS sta
a3d0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 ck. The names a
a3e0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 re of all VFS sh
a3f0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 ims and the.** f
a400: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 inal bottom-leve
a410: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 l VFS are writte
a420: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 n into memory ob
a430: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 tained from .**
a440: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
a450: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c )] and the resul
a460: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 t is stored in t
a470: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c he char* variabl
a480: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f e.** that the fo
a490: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f urth parameter o
a4a0: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f f [sqlite3_file_
a4b0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 control()] point
a4c0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c s to..** The cal
a4d0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ler is responsib
a4e0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 le for freeing t
a4f0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 he memory when d
a500: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a one. As with.**
a510: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f all file-contro
a520: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 l actions, there
a530: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 is no guarantee
a540: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 that this will
a550: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 actually.** do a
a560: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 nything. Caller
a570: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c s should initial
a580: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 ize the char* va
a590: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c riable to a NULL
a5a0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 .** pointer in c
a5b0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f ase this file-co
a5c0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 ntrol is not imp
a5d0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 lemented. This
a5e0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 file-control.**
a5f0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 is intended for
a600: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f diagnostic use o
a610: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b nly..**.** <li>[
a620: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
a630: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 AGMA]].** ^Whene
a640: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 ver a [PRAGMA] s
a650: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 tatement is pars
a660: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 ed, an [SQLITE_F
a670: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a CNTL_PRAGMA] .**
a680: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 file control is
a690: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 sent to the ope
a6a0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d n [sqlite3_file]
a6b0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f object correspo
a6c0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 nding.** to the
a6d0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f database file to
a6e0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d which the pragm
a6f0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 a statement refe
a700: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e rs. ^The argumen
a710: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c t.** to the [SQL
a720: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
a730: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 ] file control i
a740: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a s an array of.**
a750: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
a760: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e ings (char**) in
a770: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e which the secon
a780: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 d element of the
a790: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 array.** is the
a7a0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 name of the pra
a7b0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 gma and the thir
a7c0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 d element is the
a7d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
a7e0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 .** pragma or NU
a7f0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 LL if the pragma
a800: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 has no argument
a810: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 . ^The handler
a820: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 for an.** [SQLIT
a830: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
a840: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e file control can
a850: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 optionally make
a860: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 the first eleme
a870: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 nt.** of the cha
a880: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 r** argument poi
a890: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f nt to a string o
a8a0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
a8b0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d lite3_mprintf()]
a8c0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 .** or the equiv
a8d0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 alent and that s
a8e0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d tring will becom
a8f0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 e the result of
a900: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a the pragma or.**
a910: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
a920: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 ge if the pragma
a930: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a fails. ^If the.
a940: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [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 72 65 74 75 72 6e 73 20 5b 53 ntrol returns [S
a970: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c QLITE_NOTFOUND],
a980: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a then normal .**
a990: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 [PRAGMA] proces
a9a0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 sing continues.
a9b0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 ^If the [SQLITE
a9c0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a _FCNTL_PRAGMA].*
a9d0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 * file control r
a9e0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
a9f0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 K], then the par
aa00: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 ser assumes that
aa10: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 the.** VFS has
aa20: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 handled the PRAG
aa30: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 MA itself and th
aa40: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 e parser generat
aa50: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 es a no-op.** pr
aa60: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
aa70: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e if result strin
aa80: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 g is NULL, or th
aa90: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 at returns a cop
aaa0: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 y.** of the resu
aab0: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 lt string if the
aac0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e string is non-N
aad0: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ULL..** ^If the
aae0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
aaf0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 AGMA] file contr
ab00: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e ol returns.** an
ab10: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 y result code ot
ab20: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
ab30: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f _OK] or [SQLITE_
ab40: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 NOTFOUND], that
ab50: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 means.** that th
ab60: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 e VFS encountere
ab70: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 d an error while
ab80: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 handling the [P
ab90: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a RAGMA] and the.*
aba0: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 * compilation of
abb0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c the PRAGMA fail
abc0: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e s with an error.
abd0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ^The [SQLITE_F
abe0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 CNTL_PRAGMA].**
abf0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 file control occ
ac00: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e urs at the begin
ac10: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 ning of pragma s
ac20: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 tatement analysi
ac30: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 s and so.** it i
ac40: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 s able to overri
ac50: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 de built-in [PRA
ac60: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e GMA] statements.
ac70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
ac80: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 ITE_FCNTL_BUSYHA
ac90: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 NDLER]].** ^The
aca0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 [SQLITE_FCNTL_BU
acb0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 SYHANDLER].** fi
acc0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 le-control may b
acd0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c e invoked by SQL
ace0: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ite on the datab
acf0: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a ase file handle.
ad00: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 ** shortly after
ad10: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e it is opened in
ad20: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 order to provid
ad30: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 e a custom VFS w
ad40: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f ith access.** to
ad50: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 the connections
ad60: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 busy-handler ca
ad70: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 llback. The argu
ad80: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 ment is of type
ad90: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 (void **).** - a
ada0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 n array of two (
adb0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 void *) values.
adc0: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 The first (void
add0: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e *) actually poin
ade0: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 ts.** to a funct
adf0: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 ion of type (int
ae00: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 (*)(void *)). I
ae10: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b n order to invok
ae20: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e e the connection
ae30: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 s.** busy-handle
ae40: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e r, this function
ae50: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b should be invok
ae60: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f ed with the seco
ae70: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a nd (void *) in.*
ae80: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 * the array as t
ae90: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 he only argument
aea0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 . If it returns
aeb0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 non-zero, then t
aec0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 he operation.**
aed0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 should be retrie
aee0: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 d. If it returns
aef0: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f zero, the custo
af00: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 m VFS should aba
af10: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 ndon the.** curr
af20: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a ent operation..*
af30: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
af40: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 E_FCNTL_TEMPFILE
af50: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 NAME]].** ^Appli
af60: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b cation can invok
af70: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 e the [SQLITE_FC
af80: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 NTL_TEMPFILENAME
af90: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a ] file-control.*
afa0: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 * to have SQLite
afb0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 generate a.** t
afc0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d emporary filenam
afd0: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 e using the same
afe0: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 algorithm that
aff0: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 is followed to g
b000: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f enerate.** tempo
b010: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 rary filenames f
b020: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 or TEMP tables a
b030: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 nd other interna
b040: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 l uses. The.**
b050: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
b060: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 be a char** whic
b070: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 h will be filled
b080: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 with the filena
b090: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e me.** written in
b0a0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
b0b0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
b0c0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 _malloc()]. The
b0d0: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a caller should.*
b0e0: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 * invoke [sqlite
b0f0: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 3_free()] on the
b100: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 result to avoid
b110: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a a memory leak..
b120: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
b130: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 TE_FCNTL_MMAP_SI
b140: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ZE]].** The [SQL
b150: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 ITE_FCNTL_MMAP_S
b160: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f IZE] file contro
b170: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 l is used to que
b180: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a ry or set the.**
b190: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
b1a0: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69 of bytes that wi
b1b0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d ll be used for m
b1c0: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f emory-mapped I/O
b1d0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e ..** The argumen
b1e0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
b1f0: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 o a value of typ
b200: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 e sqlite3_int64
b210: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 that.** is an ad
b220: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e visory maximum n
b230: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
b240: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 n the file to me
b250: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a mory map. The.*
b260: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 * pointer is ove
b270: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 rwritten with th
b280: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 e old value. Th
b290: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 e limit is not c
b2a0: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 hanged if.** the
b2b0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c value originall
b2c0: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 y pointed to is
b2d0: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f negative, and so
b2e0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d the current lim
b2f0: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 it .** can be qu
b300: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 eried by passing
b310: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f in a pointer to
b320: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 a negative numb
b330: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c er. This.** fil
b340: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 e-control is use
b350: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 d internally to
b360: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d implement [PRAGM
b370: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a A mmap_size]..**
b380: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
b390: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a _FCNTL_TRACE]].*
b3a0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
b3b0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 NTL_TRACE] file
b3c0: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 control provides
b3d0: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d advisory inform
b3e0: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 ation.** to the
b3f0: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 VFS about what t
b400: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 he higher layers
b410: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 of the SQLite s
b420: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a tack are doing..
b430: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e ** This file con
b440: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 trol is used by
b450: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 some VFS activit
b460: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 y tracing [shims
b470: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 ]..** The argume
b480: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 nt is a zero-ter
b490: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 minated string.
b4a0: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 Higher layers i
b4b0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 n the.** SQLite
b4c0: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 stack may genera
b4d0: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 te instances of
b4e0: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f this file contro
b4f0: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c l if.** the [SQL
b500: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 ITE_USE_FCNTL_TR
b510: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ACE] compile-tim
b520: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 e option is enab
b530: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b led..**.** <li>[
b540: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 [SQLITE_FCNTL_HA
b550: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 S_MOVED]].** The
b560: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 [SQLITE_FCNTL_H
b570: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 AS_MOVED] file c
b580: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 ontrol interpret
b590: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 s its argument a
b5a0: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 s a.** pointer t
b5b0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 o an integer and
b5c0: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f it writes a boo
b5d0: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 lean into that i
b5e0: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 nteger depending
b5f0: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f .** on whether o
b600: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 r not the file h
b610: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c as been renamed,
b620: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 moved, or delet
b630: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 ed since it.** w
b640: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e as first opened.
b650: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
b660: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
b670: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 SET_HANDLE]].**
b680: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
b690: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 L_WIN32_SET_HAND
b6a0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 LE] opcode is us
b6b0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 ed for debugging
b6c0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
b6d0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 e causes the xFi
b6e0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
b6f0: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c to swap the fil
b700: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 e handle with th
b710: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 e one.** pointed
b720: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 to by the pArg
b730: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 argument. This
b740: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 capability is us
b750: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
b760: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 g.** and only ne
b770: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 eds to be suppor
b780: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f ted when SQLITE_
b790: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e TEST is defined.
b7a0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
b7b0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c ITE_FCNTL_WAL_BL
b7c0: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 OCK]].** The [SQ
b7d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 LITE_FCNTL_WAL_B
b7e0: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 LOCK] is a signa
b7f0: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 l to the VFS lay
b800: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 er that it might
b810: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 .** be advantage
b820: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 ous to block on
b830: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 the next WAL loc
b840: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 k if the lock is
b850: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 not immediately
b860: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 .** available.
b870: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 The WAL subsyste
b880: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69 m issues this si
b890: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 gnal during rare
b8a0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 .** circumstance
b8b0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 s in order to fi
b8c0: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 x a problem with
b8d0: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 priority invers
b8e0: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ion..** Applicat
b8f0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e ions should <em>
b900: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 not</em> use thi
b910: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a s file-control..
b920: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
b930: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d TE_FCNTL_ZIPVFS]
b940: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
b950: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f _FCNTL_ZIPVFS] o
b960: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 pcode is impleme
b970: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f nted by zipvfs o
b980: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a nly. All other.*
b990: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 * VFS should ret
b9a0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f urn SQLITE_NOTFO
b9b0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 UND for this opc
b9c0: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ode..**.** <li>[
b9d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 54 [SQLITE_FCNTL_OT
b9e0: 41 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 A]].** The [SQLI
b9f0: 54 45 5f 46 43 4e 54 4c 5f 4f 54 41 5d 20 6f 70 TE_FCNTL_OTA] op
ba00: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e code is implemen
ba10: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69 ted by the speci
ba20: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a al VFS used by.*
ba30: 2a 20 74 68 65 20 4f 54 41 20 65 78 74 65 6e 73 * the OTA extens
ba40: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f ion only. All o
ba50: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 ther VFS should
ba60: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f return SQLITE_NO
ba70: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 TFOUND for.** th
ba80: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 is opcode. .**
ba90: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </ul>.*/.#define
baa0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f SQLITE_FCNTL_LO
bab0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 CKSTATE
bac0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
bad0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 SQLITE_FCNTL_GET
bae0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
baf0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
bb00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f QLITE_FCNTL_SET_
bb10: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 LOCKPROXYFILE
bb20: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
bb30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f LITE_FCNTL_LAST_
bb40: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 ERRNO
bb50: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
bb60: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 ITE_FCNTL_SIZE_H
bb70: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 INT
bb80: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 5.#define SQLI
bb90: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 TE_FCNTL_CHUNK_S
bba0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 IZE
bbb0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
bbc0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 E_FCNTL_FILE_POI
bbd0: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 NTER
bbe0: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 7.#define SQLITE
bbf0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 _FCNTL_SYNC_OMIT
bc00: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 TED 8
bc10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
bc20: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 FCNTL_WIN32_AV_R
bc30: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a ETRY 9.
bc40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
bc50: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c CNTL_PERSIST_WAL
bc60: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 10.#
bc70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
bc80: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 NTL_OVERWRITE
bc90: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 11.#d
bca0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
bcb0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 TL_VFSNAME
bcc0: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 12.#de
bcd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
bce0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 L_POWERSAFE_OVER
bcf0: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 WRITE 13.#def
bd00: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
bd10: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 _PRAGMA
bd20: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 14.#defi
bd30: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
bd40: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 BUSYHANDLER
bd50: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 15.#defin
bd60: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 e SQLITE_FCNTL_T
bd70: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 EMPFILENAME
bd80: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 16.#define
bd90: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d SQLITE_FCNTL_MM
bda0: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 AP_SIZE
bdb0: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 18.#define
bdc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 SQLITE_FCNTL_TRA
bdd0: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CE
bde0: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 19.#define S
bdf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f QLITE_FCNTL_HAS_
be00: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20 MOVED
be10: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 20.#define SQ
be20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 LITE_FCNTL_SYNC
be30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
be40: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 21.#define SQL
be50: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 ITE_FCNTL_COMMIT
be60: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 _PHASETWO
be70: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 22.#define SQLI
be80: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 TE_FCNTL_WIN32_S
be90: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 ET_HANDLE
bea0: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 23.#define SQLIT
beb0: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 E_FCNTL_WAL_BLOC
bec0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 K 2
bed0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
bee0: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 _FCNTL_ZIPVFS
bef0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 25
bf00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
bf10: 46 43 4e 54 4c 5f 4f 54 41 20 20 20 20 20 20 20 FCNTL_OTA
bf20: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 26.
bf30: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e ./* deprecated n
bf40: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ames */.#define
bf50: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 SQLITE_GET_LOCKP
bf60: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 ROXYFILE SQ
bf70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c LITE_FCNTL_GET_L
bf80: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 OCKPROXYFILE.#de
bf90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f fine SQLITE_SET_
bfa0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 LOCKPROXYFILE
bfb0: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f SQLITE_FCNTL_
bfc0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c SET_LOCKPROXYFIL
bfd0: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 E.#define SQLITE
bfe0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 _LAST_ERRNO
bff0: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 SQLITE_F
c000: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a CNTL_LAST_ERRNO.
c010: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
c020: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a : Mutex Handle.*
c030: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d *.** The mutex m
c040: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c odule within SQL
c050: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c ite defines [sql
c060: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 ite3_mutex] to b
c070: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 e an.** abstract
c080: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 type for a mute
c090: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 x object. The S
c0a0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 QLite core never
c0b0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 looks.** at the
c0c0: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 internal repres
c0d0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b entation of an [
c0e0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 sqlite3_mutex].
c0f0: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c It only.** deal
c100: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 s with pointers
c110: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
c120: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a mutex] object..*
c130: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 *.** Mutexes are
c140: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b created using [
c150: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
c160: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 loc()]..*/.typed
c170: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
c180: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 3_mutex sqlite3_
c190: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 mutex;../*.** CA
c1a0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
c1b0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a face Object.**.*
c1c0: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
c1d0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
c1e0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
c1f0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
c200: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c tween.** the SQL
c210: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 ite core and the
c220: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 underlying oper
c230: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 ating system. T
c240: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 he "vfs".** in t
c250: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f he name of the o
c260: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 bject stands for
c270: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 "virtual file s
c280: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 ystem". See.**
c290: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 the [VFS | VFS d
c2a0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
c2b0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d r further inform
c2c0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
c2d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 value of the iV
c2e0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 ersion field is
c2f0: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 initially 1 but
c300: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e may be larger in
c310: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 .** future versi
c320: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 ons of SQLite.
c330: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 Additional field
c340: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 s may be appende
c350: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a d to this.** obj
c360: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 ect when the iVe
c370: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 rsion value is i
c380: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 ncreased. Note
c390: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 that the structu
c3a0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c re.** of the sql
c3b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 ite3_vfs object
c3c0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 changes in the t
c3d0: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 ransaction betwe
c3e0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 en.** SQLite ver
c3f0: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 sion 3.5.9 and 3
c400: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 .6.0 and yet the
c410: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 iVersion field
c420: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 was not.** modif
c430: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ied..**.** The s
c440: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 zOsFile field is
c450: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
c460: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c subclassed [sql
c470: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 ite3_file].** st
c480: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 ructure used by
c490: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 this VFS. mxPat
c4a0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 hname is the max
c4b0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a imum length of.*
c4c0: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 * a pathname in
c4d0: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 this VFS..**.**
c4e0: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 Registered sqlit
c4f0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 e3_vfs objects a
c500: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e re kept on a lin
c510: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 ked list formed
c520: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 by.** the pNext
c530: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 pointer. The [s
c540: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 qlite3_vfs_regis
c550: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ter()].** and [s
c560: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 qlite3_vfs_unreg
c570: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 ister()] interfa
c580: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 ces manage this
c590: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 list.** in a thr
c5a0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 ead-safe way. T
c5b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f he [sqlite3_vfs_
c5c0: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 find()] interfac
c5d0: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 e.** searches th
c5e0: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 e list. Neither
c5f0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
c600: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 code nor the VF
c610: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 S.** implementat
c620: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 ion should use t
c630: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 he pNext pointer
c640: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 ..**.** The pNex
c650: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f t field is the o
c660: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 nly field in the
c670: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 sqlite3_vfs.**
c680: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 structure that S
c690: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 QLite will ever
c6a0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 modify. SQLite
c6b0: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 will only access
c6c0: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 .** or modify th
c6d0: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 is field while h
c6e0: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 olding a particu
c6f0: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 lar static mutex
c700: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
c710: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 tion should neve
c720: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e r modify anythin
c730: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c g within the sql
c740: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 ite3_vfs.** obje
c750: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 ct once the obje
c760: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 ct has been regi
c770: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 stered..**.** Th
c780: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f e zName field ho
c790: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 lds the name of
c7a0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 the VFS module.
c7b0: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a The name must.*
c7c0: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f * be unique acro
c7d0: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c ss all VFS modul
c7e0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 es..**.** [[sqli
c7f0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a te3_vfs.xOpen]].
c800: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 ** ^SQLite guara
c810: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a ntees that the z
c820: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
c830: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 er to xOpen.** i
c840: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 s either a NULL
c850: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e pointer or strin
c860: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 g obtained.** fr
c870: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 om xFullPathname
c880: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f () with an optio
c890: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 nal suffix added
c8a0: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 ..** ^If a suffi
c8b0: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 x is added to th
c8c0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 e zFilename para
c8d0: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a meter, it will.*
c8e0: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 * consist of a s
c8f0: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 ingle "-" charac
c900: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 ter followed by
c910: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 no more than.**
c920: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 11 alphanumeric
c930: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 and/or "-" chara
c940: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 cters..** ^SQLit
c950: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e e further guaran
c960: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 tees that.** the
c970: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 string will be
c980: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e valid and unchan
c990: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 ged until xClose
c9a0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e () is.** called.
c9b0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
c9c0: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 previous sentenc
c9d0: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 e,.** the [sqlit
c9e0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 e3_file] can saf
c9f0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e ely store a poin
ca00: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 ter to the.** fi
ca10: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 lename if it nee
ca20: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 ds to remember t
ca30: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 he filename for
ca40: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 some reason..**
ca50: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 If the zFilename
ca60: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
ca70: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f pen is a NULL po
ca80: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e inter then xOpen
ca90: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 .** must invent
caa0: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 its own temporar
cab0: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 y name for the f
cac0: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 ile. ^Whenever
cad0: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d the .** xFilenam
cae0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e e parameter is N
caf0: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f ULL it will also
cb00: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 be the case tha
cb10: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 t the.** flags p
cb20: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e arameter will in
cb30: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 clude [SQLITE_OP
cb40: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
cb50: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 ]..**.** The fla
cb60: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
cb70: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 Open() includes
cb80: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a all bits set in.
cb90: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 ** the flags arg
cba0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 ument to [sqlite
cbb0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 3_open_v2()]. O
cbc0: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r if [sqlite3_op
cbd0: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c en()].** or [sql
cbe0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 ite3_open16()] i
cbf0: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 s used, then fla
cc00: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c gs includes at l
cc10: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f east.** [SQLITE_
cc20: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 OPEN_READWRITE]
cc30: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 | [SQLITE_OPEN_C
cc40: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 REATE]. .** If x
cc50: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 Open() opens a f
cc60: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 ile read-only th
cc70: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 en it sets *pOut
cc80: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c Flags to.** incl
cc90: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ude [SQLITE_OPEN
cca0: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 _READONLY]. Oth
ccb0: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 er bits in *pOut
ccc0: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 Flags may be set
ccd0: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 ..**.** ^(SQLite
cce0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f will also add o
ccf0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
cd00: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 ing flags to the
cd10: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c xOpen().** call
cd20: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 , depending on t
cd30: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 he object being
cd40: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 opened:.**.** <u
cd50: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c l>.** <li> [SQL
cd60: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
cd70: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
cd80: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 TE_OPEN_MAIN_JOU
cd90: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
cda0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
cdb0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
cdc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
cdd0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
cde0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
cdf0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 RANSIENT_DB].**
ce00: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
ce10: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a EN_SUBJOURNAL].*
ce20: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
ce30: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
ce40: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
ce50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a QLITE_OPEN_WAL].
ce60: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a ** </ul>)^.**.**
ce70: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d The file I/O im
ce80: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e plementation can
ce90: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 use the object
cea0: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a type flags to.**
ceb0: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 change the way
cec0: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 it deals with fi
ced0: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c les. For exampl
cee0: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f e, an applicatio
cef0: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e n.** that does n
cf00: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 ot care about cr
cf10: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 ash recovery or
cf20: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d rollback might m
cf30: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 ake.** the open
cf40: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c of a journal fil
cf50: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 e a no-op. Writ
cf60: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e es to this journ
cf70: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f al would.** also
cf80: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 be no-ops, and
cf90: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 any attempt to r
cfa0: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 ead the journal
cfb0: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 would return.**
cfc0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f SQLITE_IOERR. O
cfd0: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 r the implementa
cfe0: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 tion might recog
cff0: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 nize that a data
d000: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c base.** file wil
d010: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d l be doing page-
d020: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 aligned sector r
d030: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 eads and writes
d040: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f in a random.** o
d050: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 rder and set up
d060: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 its I/O subsyste
d070: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a m accordingly..*
d080: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 *.** SQLite migh
d090: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f t also add one o
d0a0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
d0b0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 flags to the xOp
d0c0: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a en method:.**.**
d0d0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
d0e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
d0f0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 EONCLOSE].** <li
d100: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 > [SQLITE_OPEN_E
d110: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 XCLUSIVE].** </u
d120: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 l>.**.** The [SQ
d130: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
d140: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 ONCLOSE] flag me
d150: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f ans the file sho
d160: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 uld be.** delete
d170: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f d when it is clo
d180: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 sed. ^The [SQLI
d190: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
d1a0: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 CLOSE].** will b
d1b0: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 e set for TEMP d
d1c0: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 atabases and the
d1d0: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 ir journals, tra
d1e0: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 nsient.** databa
d1f0: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 ses, and subjour
d200: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nals..**.** ^The
d210: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
d220: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 CLUSIVE] flag is
d230: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 always used in
d240: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 conjunction.** w
d250: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
d260: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 OPEN_CREATE] fla
d270: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 g, which are bot
d280: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e h directly.** an
d290: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f alogous to the O
d2a0: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 _EXCL and O_CREA
d2b0: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 T flags of the P
d2c0: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 OSIX open().** A
d2d0: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f PI. The SQLITE_
d2e0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 OPEN_EXCLUSIVE f
d2f0: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 lag, when paired
d300: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 with the .** SQ
d310: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
d320: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 , is used to ind
d330: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 icate that file
d340: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a should always.**
d350: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 be created, and
d360: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 that it is an e
d370: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 rror if it alrea
d380: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 dy exists..** It
d390: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 is <i>not</i> u
d3a0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 sed to indicate
d3b0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 the file should
d3c0: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f be opened .** fo
d3d0: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 r exclusive acce
d3e0: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 ss..**.** ^At le
d3f0: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 ast szOsFile byt
d400: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 es of memory are
d410: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 allocated by SQ
d420: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 Lite.** to hold
d430: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
d440: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 le] structure pa
d450: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 ssed as the thir
d460: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f d.** argument to
d470: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 xOpen. The xOp
d480: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e en method does n
d490: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c ot have to.** al
d4a0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 locate the struc
d4b0: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 ture; it should
d4c0: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e just fill it in.
d4d0: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 Note that.** t
d4e0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 he xOpen method
d4f0: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c must set the sql
d500: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
d510: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 ds to either.**
d520: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 a valid [sqlite3
d530: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
d540: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 ect or to NULL.
d550: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a xOpen must do.*
d560: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 * this even if t
d570: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 he open fails.
d580: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 SQLite expects t
d590: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f hat the sqlite3_
d5a0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a file.pMethods.**
d5b0: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 element will be
d5c0: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 valid after xOp
d5d0: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 en returns regar
d5e0: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 dless of the suc
d5f0: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 cess.** or failu
d600: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 re of the xOpen
d610: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 call..**.** [[sq
d620: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 lite3_vfs.xAcces
d630: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 s]].** ^The flag
d640: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 s argument to xA
d650: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b ccess() may be [
d660: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
d670: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 ISTS].** to test
d680: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e for the existen
d690: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 ce of a file, or
d6a0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
d6b0: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a READWRITE] to.**
d6c0: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 test whether a
d6d0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 file is readable
d6e0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f and writable, o
d6f0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 r [SQLITE_ACCESS
d700: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 _READ].** to tes
d710: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 t whether a file
d720: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 is at least rea
d730: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c dable. The fil
d740: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 e can be a.** di
d750: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e rectory..**.** ^
d760: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 SQLite will alwa
d770: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c ys allocate at l
d780: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b east mxPathname+
d790: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 1 bytes for the.
d7a0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 ** output buffer
d7b0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 xFullPathname.
d7c0: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 The exact size
d7d0: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 of the output bu
d7e0: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 ffer.** is also
d7f0: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 passed as a para
d800: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d meter to both m
d810: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f ethods. If the o
d820: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 utput buffer.**
d830: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f is not large eno
d840: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e ugh, [SQLITE_CAN
d850: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 TOPEN] should be
d860: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 returned. Since
d870: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 this is.** hand
d880: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 led as a fatal e
d890: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 rror by SQLite,
d8a0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 vfs implementati
d8b0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 ons should endea
d8c0: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e vor.** to preven
d8d0: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e t this by settin
d8e0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 g mxPathname to
d8f0: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c a sufficiently l
d900: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a arge value..**.*
d910: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
d920: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 s(), xSleep(), x
d930: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 CurrentTime(), a
d940: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 nd xCurrentTimeI
d950: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 nt64().** interf
d960: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 aces are not str
d970: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 ictly a part of
d980: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 the filesystem,
d990: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 but they are.**
d9a0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 included in the
d9b0: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f VFS structure fo
d9c0: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a r completeness..
d9d0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 ** The xRandomne
d9e0: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 ss() function at
d9f0: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e tempts to return
da00: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a nBytes bytes.**
da10: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 of good-quality
da20: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f randomness into
da30: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 zOut. The retu
da40: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 rn value is.** t
da50: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 he actual number
da60: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e of bytes of ran
da70: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 domness obtained
da80: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 ..** The xSleep(
da90: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 ) method causes
daa0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 the calling thre
dab0: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 ad to sleep for
dac0: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 at.** least the
dad0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 number of micros
dae0: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e econds given. ^
daf0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 The xCurrentTime
db00: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 ().** method ret
db10: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 urns a Julian Da
db20: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 y Number for the
db30: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e current date an
db40: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 d time as.** a f
db50: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 loating point va
db60: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 lue..** ^The xCu
db70: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
db80: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c method returns,
db90: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 as an integer,
dba0: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 the Julian.** Da
dbb0: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c y Number multipl
dbc0: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 ied by 86400000
dbd0: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d (the number of m
dbe0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a illiseconds in .
dbf0: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 ** a 24-hour day
dc00: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ). .** ^SQLite
dc10: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 will use the xCu
dc20: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
dc30: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 method to get t
dc40: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 he current.** da
dc50: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 te and time if t
dc60: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 hat method is av
dc70: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 ailable (if iVer
dc80: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a sion is 2 or .**
dc90: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 greater and the
dca0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 function pointe
dcb0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 r is not NULL) a
dcc0: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 nd will fall bac
dcd0: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 k.** to xCurrent
dce0: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 Time() if xCurre
dcf0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 ntTimeInt64() is
dd00: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a unavailable..**
dd10: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 .** ^The xSetSys
dd20: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 temCall(), xGetS
dd30: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 ystemCall(), and
dd40: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c xNestSystemCall
dd50: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
dd60: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 are not used by
dd70: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 the SQLite core
dd80: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 . These optiona
dd90: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 l interfaces are
dda0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 provided.** by
ddb0: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 some VFSes to fa
ddc0: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 cilitate testing
ddd0: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 of the VFS code
dde0: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 . By overriding
ddf0: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 .** system calls
de00: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 with functions
de10: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f under its contro
de20: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 l, a test progra
de30: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 m can.** simulat
de40: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 e faults and err
de50: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 or conditions th
de60: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 at would otherwi
de70: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a se be difficult.
de80: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 ** or impossible
de90: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 to induce. The
dea0: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 set of system c
deb0: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 alls that can be
dec0: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 overridden.** v
ded0: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 aries from one V
dee0: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 FS to another, a
def0: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 nd from one vers
df00: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ion of the same
df10: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 VFS to the.** ne
df20: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e xt. Application
df30: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 s that use these
df40: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 interfaces must
df50: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 be prepared for
df60: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f any.** or all o
df70: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 f these interfac
df80: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 es to be NULL or
df90: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 for their behav
dfa0: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a ior to change.**
dfb0: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 from one releas
dfc0: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 e to the next.
dfd0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 Applications mus
dfe0: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f t not attempt to
dff0: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f access.** any o
e000: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 f these methods
e010: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 if the iVersion
e020: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 of the VFS is le
e030: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 ss than 3..*/.ty
e040: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
e050: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 ite3_vfs sqlite3
e060: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f _vfs;.typedef vo
e070: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 id (*sqlite3_sys
e080: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b call_ptr)(void);
e090: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
e0a0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 vfs {. int iVer
e0b0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 sion;
e0c0: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 /* Structure ve
e0d0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 rsion number (cu
e0e0: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 rrently 3) */.
e0f0: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 int szOsFile;
e100: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 /* Size
e110: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 of subclassed s
e120: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 qlite3_file */.
e130: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b int mxPathname;
e140: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
e150: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 imum file pathna
e160: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 me length */. s
e170: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 qlite3_vfs *pNex
e180: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 t; /* Next
e190: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a registered VFS *
e1a0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
e1b0: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 zName; /*
e1c0: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 Name of this vir
e1d0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d tual file system
e1e0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 */. void *pApp
e1f0: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f Data; /
e200: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 * Pointer to app
e210: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 lication-specifi
e220: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 c data */. int
e230: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 (*xOpen)(sqlite3
e240: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
e250: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 r *zName, sqlite
e260: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 3_file*,.
e270: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 int flag
e280: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 s, int *pOutFlag
e290: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c s);. int (*xDel
e2a0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ete)(sqlite3_vfs
e2b0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
e2c0: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 Name, int syncDi
e2d0: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 r);. int (*xAcc
e2e0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
e2f0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
e300: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c Name, int flags,
e310: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
e320: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 int (*xFullPat
e330: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 hname)(sqlite3_v
e340: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
e350: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 *zName, int nOut
e360: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 , char *zOut);.
e370: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e void *(*xDlOpen
e380: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e390: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c const char *zFil
e3a0: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 ename);. void (
e3b0: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 *xDlError)(sqlit
e3c0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 e3_vfs*, int nBy
e3d0: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 te, char *zErrMs
e3e0: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 g);. void (*(*x
e3f0: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 DlSym)(sqlite3_v
e400: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 fs*,void*, const
e410: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 char *zSymbol))
e420: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 (void);. void (
e430: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 *xDlClose)(sqlit
e440: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b e3_vfs*, void*);
e450: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d . int (*xRandom
e460: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 ness)(sqlite3_vf
e470: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
e480: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e har *zOut);. in
e490: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 t (*xSleep)(sqli
e4a0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 te3_vfs*, int mi
e4b0: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 croseconds);. i
e4c0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d nt (*xCurrentTim
e4d0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
e4e0: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 double*);. int
e4f0: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 (*xGetLastError
e500: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e510: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 int, char *);.
e520: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
e530: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
e540: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 version 1 of th
e550: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a e sqlite_vfs obj
e560: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 ect. ** definit
e570: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 ion. Those that
e580: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 follow are adde
e590: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f d in version 2 o
e5a0: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 r later. */. i
e5b0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d nt (*xCurrentTim
e5c0: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f eInt64)(sqlite3_
e5d0: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e vfs*, sqlite3_in
e5e0: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a t64*);. /*. **
e5f0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f The methods abo
e600: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f ve are in versio
e610: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 ns 1 and 2 of th
e620: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a e sqlite_vfs obj
e630: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 ect.. ** Those
e640: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 below are for ve
e650: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 rsion 3 and grea
e660: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 ter.. */. int
e670: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c (*xSetSystemCall
e680: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e690: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
e6a0: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 e, sqlite3_sysca
e6b0: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 ll_ptr);. sqlit
e6c0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 e3_syscall_ptr (
e6d0: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 *xGetSystemCall)
e6e0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
e6f0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
e700: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 );. const char
e710: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 *(*xNextSystemCa
e720: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ll)(sqlite3_vfs*
e730: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
e740: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 ame);. /*. **
e750: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
e760: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
e770: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 s 1 through 3 of
e780: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 the sqlite_vfs
e790: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 object.. ** New
e7a0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
e7b0: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 ppended in figur
e7c0: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 e versions. The
e7d0: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 iVersion. ** v
e7e0: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d alue will increm
e7f0: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 ent whenever thi
e800: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f s happens. . */
e810: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
e820: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 REF: Flags for t
e830: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d he xAccess VFS m
e840: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ethod.**.** Thes
e850: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
e860: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 nts can be used
e870: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 as the third par
e880: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ameter to.** the
e890: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
e8a0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 of an [sqlite3_v
e8b0: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 fs] object. The
e8c0: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 y determine.** w
e8d0: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d hat kind of perm
e8e0: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 issions the xAcc
e8f0: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f ess method is lo
e900: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 oking for..** Wi
e910: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
e920: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 _EXISTS, the xAc
e930: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 cess method.** s
e940: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 imply checks whe
e950: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 ther the file ex
e960: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 ists..** With SQ
e970: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
e980: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 WRITE, the xAcce
e990: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
e9a0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
e9b0: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 named directory
e9c0: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 is both readable
e9d0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a and writable.**
e9e0: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 (in other words
e9f0: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 , if files can b
ea00: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 e added, removed
ea10: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 , and renamed wi
ea20: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 thin.** the dire
ea30: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 ctory)..** The S
ea40: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
ea50: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 DWRITE constant
ea60: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 is currently use
ea70: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a d only by the.**
ea80: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
ea90: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 ectory pragma],
eaa0: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c though this coul
eab0: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 d change in a fu
eac0: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 ture.** release
ead0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 of SQLite..** Wi
eae0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
eaf0: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 _READ, the xAcce
eb00: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
eb10: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
eb20: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 file is readable
eb30: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 . The SQLITE_AC
eb40: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 CESS_READ consta
eb50: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 nt is.** current
eb60: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 ly unused, thoug
eb70: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 h it might be us
eb80: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 ed in a future r
eb90: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c elease of.** SQL
eba0: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ite..*/.#define
ebb0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
ebc0: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e ISTS 0.#defin
ebd0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
ebe0: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a READWRITE 1 /*
ebf0: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 Used by PRAGMA
ec00: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
ec10: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 tory */.#define
ec20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
ec30: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 AD 2 /* U
ec40: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 nused */../*.**
ec50: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
ec60: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b for the xShmLock
ec70: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a VFS method.**.*
ec80: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
ec90: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
eca0: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 the various loc
ecb0: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a king operations.
ecc0: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 ** allowed by th
ecd0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
ece0: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f d of [sqlite3_io
ecf0: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a _methods]. The.
ed00: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 ** following are
ed10: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 the only legal
ed20: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 combinations of
ed30: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 flags to the.**
ed40: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a xShmLock method:
ed50: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
ed60: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f li> SQLITE_SHM_
ed70: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 LOCK | SQLITE_SH
ed80: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e M_SHARED.** <li>
ed90: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 SQLITE_SHM_LOC
eda0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 K | SQLITE_SHM_E
edb0: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e XCLUSIVE.** <li>
edc0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c SQLITE_SHM_UNL
edd0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
ede0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 _SHARED.** <li>
edf0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
ee00: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
ee10: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 EXCLUSIVE.** </u
ee20: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e l>.**.** When un
ee30: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d locking, the sam
ee40: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c e SHARED or EXCL
ee50: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 USIVE flag must
ee60: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a be supplied as.*
ee70: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 * was given on t
ee80: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
ee90: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 lock. .**.** T
eea0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 he xShmLock meth
eeb0: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f od can transitio
eec0: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b n between unlock
eed0: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 ed and SHARED or
eee0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f .** between unlo
eef0: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 cked and EXCLUSI
ef00: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 VE. It cannot t
ef10: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 ransition betwee
ef20: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 n SHARED.** and
ef30: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 EXCLUSIVE..*/.#d
ef40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
ef50: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a _UNLOCK 1.
ef60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
ef70: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 HM_LOCK
ef80: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
ef90: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 _SHM_SHARED
efa0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
efb0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
efc0: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 8../*.** CAP
efd0: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 I3REF: Maximum x
efe0: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a ShmLock index.**
eff0: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b .** The xShmLock
f000: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 method on [sqli
f010: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
f020: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a may use values.*
f030: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 * between 0 and
f040: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 this upper bound
f050: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 as its "offset"
f060: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 argument..** Th
f070: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 e SQLite core wi
f080: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 ll never attempt
f090: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 to acquire or r
f0a0: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b elease a.** lock
f0b0: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 outside of this
f0c0: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e range.*/.#defin
f0d0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f e SQLITE_SHM_NLO
f0e0: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a CK 8.../*
f0f0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
f100: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c itialize The SQL
f110: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a ite Library.**.*
f120: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
f130: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
f140: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 ine initializes
f150: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 the.** SQLite li
f160: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c brary. ^The sql
f170: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
f180: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c routine.** deall
f190: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 ocates any resou
f1a0: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 rces that were a
f1b0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 llocated by sqli
f1c0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
f1d0: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 ..** These routi
f1e0: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 nes are designed
f1f0: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 to aid in proce
f200: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ss initializatio
f210: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 n and.** shutdow
f220: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 n on embedded sy
f230: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 stems. Workstat
f240: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ion applications
f250: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 using.** SQLite
f260: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 normally do not
f270: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 need to invoke
f280: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 either of these
f290: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
f2a0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
f2b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
f2c0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 s an "effective"
f2d0: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a call if it is.*
f2e0: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 * the first time
f2f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
f300: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
f310: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 during the life
f320: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 time of.** the p
f330: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 rocess, or if it
f340: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 is the first ti
f350: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 me sqlite3_initi
f360: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
f370: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ed.** following
f380: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 a call to sqlite
f390: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 3_shutdown(). ^
f3a0: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 (Only an effecti
f3b0: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 ve call.** of sq
f3c0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f3d0: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 () does any init
f3e0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c ialization. All
f3f0: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 other calls.**
f400: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d are harmless no-
f410: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 ops.)^.**.** A c
f420: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
f430: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 hutdown() is an
f440: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c "effective" call
f450: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 if it is the fi
f460: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 rst.** call to s
f470: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
f480: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 ) since the last
f490: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
f4a0: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a ize(). ^(Only.*
f4b0: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 * an effective c
f4c0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
f4d0: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 hutdown() does a
f4e0: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 ny deinitializat
f4f0: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 ion..** All othe
f500: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f r valid calls to
f510: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
f520: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 n() are harmless
f530: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a no-ops.)^.**.**
f540: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 The sqlite3_ini
f550: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 tialize() interf
f560: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 ace is threadsaf
f570: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 e, but sqlite3_s
f580: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 hutdown().** is
f590: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 not. The sqlite
f5a0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 3_shutdown() int
f5b0: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 erface must only
f5c0: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
f5d0: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 a.** single thre
f5e0: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 ad. All open [d
f5f0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
f600: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f ons] must be clo
f610: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f sed and all.** o
f620: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f ther SQLite reso
f630: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 urces must be de
f640: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 allocated prior
f650: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 to invoking.** s
f660: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
f670: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f )..**.** Among o
f680: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 ther things, ^sq
f690: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f6a0: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a () will invoke.*
f6b0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
f6c0: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c t(). Similarly,
f6d0: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f ^sqlite3_shutdo
f6e0: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 wn().** will inv
f6f0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 oke sqlite3_os_e
f700: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nd()..**.** ^The
f710: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
f720: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ize() routine re
f730: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
f740: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a ] on success..**
f750: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 ^If for some re
f760: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e ason, sqlite3_in
f770: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e itialize() is un
f780: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 able to initiali
f790: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 ze.** the librar
f7a0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 y (perhaps it is
f7b0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
f7c0: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 ate a needed res
f7d0: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 ource such.** as
f7e0: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 a mutex) it ret
f7f0: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 urns an [error c
f800: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 ode] other than
f810: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a [SQLITE_OK]..**.
f820: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
f830: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
f840: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 tine is called i
f850: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e nternally by man
f860: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 y other.** SQLit
f870: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 e interfaces so
f880: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 that an applicat
f890: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 ion usually does
f8a0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 not need to.**
f8b0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 invoke sqlite3_i
f8c0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 nitialize() dire
f8d0: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 ctly. For examp
f8e0: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 le, [sqlite3_ope
f8f0: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 n()].** calls sq
f900: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f910: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 () so the SQLite
f920: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 library will be
f930: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a automatically.*
f940: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 * initialized wh
f950: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e en [sqlite3_open
f960: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 ()] is called if
f970: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 it has not be i
f980: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c nitialized.** al
f990: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 ready. ^However
f9a0: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 , if SQLite is c
f9b0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
f9c0: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 [SQLITE_OMIT_AU
f9d0: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 TOINIT].** compi
f9e0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 le-time option,
f9f0: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 then the automat
fa00: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ic calls to sqli
fa10: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
fa20: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 .** are omitted
fa30: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 and the applicat
fa40: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 ion must call sq
fa50: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
fa60: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 () directly.** p
fa70: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e rior to using an
fa80: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 y other SQLite i
fa90: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d nterface. For m
faa0: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 aximum portabili
fab0: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 ty,.** it is rec
fac0: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
fad0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 plications alway
fae0: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 s invoke sqlite3
faf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a _initialize().**
fb00: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 directly prior
fb10: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
fb20: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
fb30: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c ace. Future rel
fb40: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 eases.** of SQLi
fb50: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 te may require t
fb60: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 his. In other w
fb70: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 ords, the behavi
fb80: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 or exhibited.**
fb90: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
fba0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 ompiled with [SQ
fbb0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e LITE_OMIT_AUTOIN
fbc0: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 IT] might become
fbd0: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 the.** default
fbe0: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 behavior in some
fbf0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 future release
fc00: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
fc10: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
fc20: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 init() routine d
fc30: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 oes operating-sy
fc40: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a stem specific.**
fc50: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
fc60: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 of the SQLite li
fc70: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 brary. The sqli
fc80: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
fc90: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 routine undoes t
fca0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c he effect of sql
fcb0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
fcc0: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a Typical tasks.*
fcd0: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 * performed by t
fce0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e hese routines in
fcf0: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e clude allocation
fd00: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e or deallocation
fd10: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 .** of static re
fd20: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c sources, initial
fd30: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 ization of globa
fd40: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 l variables,.**
fd50: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 setting up a def
fd60: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
fd70: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 s] module, or se
fd80: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 tting up.** a de
fd90: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
fda0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ion using [sqlit
fdb0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a e3_config()]..**
fdc0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
fdd0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
fde0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 invoke either s
fdf0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
fe00: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f .** or sqlite3_o
fe10: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 s_end() directly
fe20: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 . The applicati
fe30: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 on should only i
fe40: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
fe50: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e _initialize() an
fe60: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f d sqlite3_shutdo
fe70: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 wn(). The sqlit
fe80: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 e3_os_init().**
fe90: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c interface is cal
fea0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c led automaticall
feb0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 y by sqlite3_ini
fec0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a tialize() and.**
fed0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
fee0: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 ) is called by s
fef0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
ff00: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a ). Appropriate.
ff10: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
ff20: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f ns for sqlite3_o
ff30: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
ff40: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
ff50: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 are built into
ff60: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 SQLite when it i
ff70: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 s compiled for U
ff80: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 nix, Windows, or
ff90: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b OS/2..** When [
ffa0: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 custom builds |
ffb0: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 built for other
ffc0: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 platforms].** (u
ffd0: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
ffe0: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d _OS_OTHER=1] com
fff0: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 pile-time.** opt
10000 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 ion) the applica
10010 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 tion must supply
10020 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c a suitable impl
10030 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a ementation for.*
10040 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
10050 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
10060 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 os_end(). An ap
10070 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 plication-suppli
10080 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 ed.** implementa
10090 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
100a0 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c os_init() or sql
100b0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
100c0 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 must return [SQ
100d0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
100e0 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 ess and some oth
100f0 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 er [error code]
10100 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e upon.** failure.
10110 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
10120 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 initialize(void)
10130 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 ;.int sqlite3_sh
10140 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e utdown(void);.in
10150 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 t sqlite3_os_ini
10160 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c t(void);.int sql
10170 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 ite3_os_end(void
10180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
10190 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 EF: Configuring
101a0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 The SQLite Libra
101b0 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ry.**.** The sql
101c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
101d0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
101e0 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 to make global c
101f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 onfiguration.**
10200 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 changes to SQLit
10210 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 e in order to tu
10220 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 ne SQLite to the
10230 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 specific needs
10240 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 of.** the applic
10250 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 ation. The defa
10260 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
10270 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 n is recommended
10280 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 for most.** app
10290 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f lications and so
102a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
102b0 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 usually not nec
102c0 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a essary. It is.*
102d0 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 * provided to su
102e0 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 pport rare appli
102f0 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 cations with unu
10300 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a sual needs..**.*
10310 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
10320 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
10330 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 is not threadsa
10340 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 fe. The applica
10350 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 tion.** must ins
10360 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 ure that no othe
10370 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
10380 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 ces are invoked
10390 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 by other.** thre
103a0 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 ads while sqlite
103b0 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 3_config() is ru
103c0 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d nning. Furtherm
103d0 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e ore, sqlite3_con
103e0 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c fig().** may onl
103f0 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 y be invoked pri
10400 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e or to library in
10410 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 itialization usi
10420 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 ng.** [sqlite3_i
10430 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 nitialize()] or
10440 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 after shutdown b
10450 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 y [sqlite3_shutd
10460 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 own()]..** ^If s
10470 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
10480 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 is called after
10490 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
104a0 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 ize()] and befor
104b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 e.** [sqlite3_sh
104c0 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 utdown()] then i
104d0 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 t will return SQ
104e0 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 LITE_MISUSE..**
104f0 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 Note, however, t
10500 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e hat ^sqlite3_con
10510 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c fig() can be cal
10520 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 led as part of t
10530 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 he.** implementa
10540 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 tion of an appli
10550 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b cation-defined [
10560 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
10570 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 )]..**.** The fi
10580 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
10590 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
105a0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a is an integer.*
105b0 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e * [configuration
105c0 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 option] that de
105d0 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 termines.** what
105e0 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c property of SQL
105f0 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e ite is to be con
10600 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 figured. Subseq
10610 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a uent arguments.*
10620 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 * vary depending
10630 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 on the [configu
10640 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a ration option].*
10650 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 * in the first a
10660 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e rgument..**.** ^
10670 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 When a configura
10680 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 tion option is s
10690 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 et, sqlite3_conf
106a0 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 ig() returns [SQ
106b0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 LITE_OK]..** ^If
106c0 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 the option is u
106d0 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 nknown or SQLite
106e0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 is unable to se
106f0 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 t the option.**
10700 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e then this routin
10710 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d e returns a non-
10720 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
10730 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
10740 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 3_config(int, ..
10750 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
10760 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 REF: Configure d
10770 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
10780 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ons.** METHOD: s
10790 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 qlite3.**.** The
107a0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
107b0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ig() interface i
107c0 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 s used to make c
107d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 onfiguration.**
107e0 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 changes to a [da
107f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
10800 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 n]. The interfa
10810 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f ce is similar to
10820 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
10830 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 fig()] except th
10840 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 at the changes a
10850 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 pply to a single
10860 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
10870 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 nnection] (speci
10880 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 fied in the firs
10890 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a t argument)..**.
108a0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ** The second ar
108b0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
108c0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 3_db_config(D,V,
108d0 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 ...) is the.**
108e0 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 [SQLITE_DBCONFIG
108f0 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e _LOOKASIDE | con
10900 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d figuration verb]
10910 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f - an integer co
10920 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 de .** that indi
10930 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63 cates what aspec
10940 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 t of the [databa
10950 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
10960 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 s being configur
10970 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e ed..** Subsequen
10980 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 t arguments vary
10990 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
109a0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
109b0 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c verb..**.** ^Cal
109c0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 ls to sqlite3_db
109d0 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e _config() return
109e0 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e SQLITE_OK if an
109f0 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 d only if.** the
10a00 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 call is conside
10a10 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a red successful..
10a20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 */.int sqlite3_d
10a30 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 b_config(sqlite3
10a40 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b *, int op, ...);
10a50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
10a60 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
10a70 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a ion Routines.**.
10a80 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
10a90 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 f this object de
10aa0 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 fines the interf
10ab0 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 ace between SQLi
10ac0 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 te.** and low-le
10ad0 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 vel memory alloc
10ae0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a ation routines..
10af0 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 **.** This objec
10b00 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c t is used in onl
10b10 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 y one place in t
10b20 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 he SQLite interf
10b30 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 ace..** A pointe
10b40 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
10b50 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
10b60 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 is the argument
10b70 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
10b80 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 onfig()] when th
10b90 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
10ba0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 option is.** [SQ
10bb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
10bc0 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 OC] or [SQLITE_C
10bd0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d ONFIG_GETMALLOC]
10be0 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 . .** By creati
10bf0 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f ng an instance o
10c00 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a f this object.**
10c10 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 and passing it
10c20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to [sqlite3_conf
10c30 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ig]([SQLITE_CONF
10c40 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 IG_MALLOC]).** d
10c50 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 uring configurat
10c60 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 ion, an applicat
10c70 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 ion can specify
10c80 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a an alternative.*
10c90 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
10ca0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f ion subsystem fo
10cb0 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 r SQLite to use
10cc0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a for all of its.*
10cd0 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 * dynamic memory
10ce0 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f needs..**.** No
10cf0 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 te that SQLite c
10d00 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 omes with severa
10d10 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f l [built-in memo
10d20 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a ry allocators].*
10d30 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 * that are perfe
10d40 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f ctly adequate fo
10d50 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 r the overwhelmi
10d60 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 ng majority of a
10d70 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 pplications.** a
10d80 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a nd that this obj
10d90 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 ect is only usef
10da0 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e ul to a tiny min
10db0 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 ority of applica
10dc0 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 tions.** with sp
10dd0 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 ecialized memory
10de0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 allocation requ
10df0 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 irements. This
10e00 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 object is.** als
10e10 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 o used during te
10e20 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 sting of SQLite
10e30 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 in order to spec
10e40 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 ify an alternati
10e50 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c ve.** memory all
10e60 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 ocator that simu
10e70 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 lates memory out
10e80 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 -of-memory condi
10e90 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 tions in.** orde
10ea0 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 r to verify that
10eb0 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 SQLite recovers
10ec0 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d gracefully from
10ed0 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 such.** conditi
10ee0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ons..**.** The x
10ef0 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 Malloc, xRealloc
10f00 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 , and xFree meth
10f10 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 ods must work li
10f20 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 ke the.** malloc
10f30 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e (), realloc() an
10f40 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f d free() functio
10f50 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ns from the stan
10f60 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
10f70 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 ** ^SQLite guara
10f80 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 ntees that the s
10f90 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
10fa0 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 o.** xRealloc is
10fb0 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 always a value
10fc0 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 returned by a pr
10fd0 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 ior call to xRou
10fe0 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a ndup..**.** xSiz
10ff0 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 e should return
11000 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 the allocated si
11010 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 ze of a memory a
11020 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 llocation.** pre
11030 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 viously obtained
11040 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 from xMalloc or
11050 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 xRealloc. The
11060 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a allocated size.*
11070 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c * is always at l
11080 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 east as big as t
11090 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a he requested siz
110a0 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 e but may be lar
110b0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ger..**.** The x
110c0 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 Roundup method r
110d0 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c eturns what woul
110e0 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 d be the allocat
110f0 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 ed size of.** a
11100 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
11110 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 n given a partic
11120 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 ular requested s
11130 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 ize. Most memor
11140 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 y.** allocators
11150 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 round up memory
11160 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c allocations at l
11170 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 east to the next
11180 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 multiple.** of
11190 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 8. Some allocat
111a0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 ors round up to
111b0 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c a larger multipl
111c0 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 e or to a power
111d0 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d of 2..** Every m
111e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
111f0 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 request coming
11200 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 in through [sqli
11210 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a te3_malloc()].**
11220 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
11230 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 lloc()] first ca
11240 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 lls xRoundup. I
11250 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 f xRoundup retur
11260 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 ns 0, .** that c
11270 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 auses the corres
11280 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 ponding memory a
11290 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 llocation to fai
112a0 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e l..**.** The xIn
112b0 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 it method initia
112c0 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 lizes the memory
112d0 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 allocator. For
112e0 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 example,.** it
112f0 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 might allocate a
11300 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 ny require mutex
11310 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 es or initialize
11320 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a internal data.*
11330 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 * structures. T
11340 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 he xShutdown met
11350 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 hod is invoked (
11360 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a indirectly) by.*
11370 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 * [sqlite3_shutd
11380 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c own()] and shoul
11390 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 d deallocate any
113a0 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 resources acqui
113b0 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e red.** by xInit.
113c0 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 The pAppData p
113d0 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 ointer is used a
113e0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d s the only param
113f0 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 eter to.** xInit
11400 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a and xShutdown..
11410 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c **.** SQLite hol
11420 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d ds the [SQLITE_M
11430 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 UTEX_STATIC_MAST
11440 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 ER] mutex when i
11450 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 t invokes.** the
11460 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 xInit method, s
11470 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 o the xInit meth
11480 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 od need not be t
11490 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a hreadsafe. The.
114a0 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 ** xShutdown met
114b0 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c hod is only call
114c0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
114d0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 _shutdown()] so
114e0 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e it does.** not n
114f0 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 eed to be thread
11500 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f safe either. Fo
11510 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 r all other meth
11520 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 ods, SQLite.** h
11530 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 olds the [SQLITE
11540 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 _MUTEX_STATIC_ME
11550 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 M] mutex as long
11560 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 as the.** [SQLI
11570 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
11580 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 TUS] configurati
11590 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 on option is tur
115a0 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a ned on (which.**
115b0 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c it is by defaul
115c0 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 t) and so the me
115d0 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 thods are automa
115e0 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a tically serializ
115f0 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 ed..** However,
11600 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 if [SQLITE_CONFI
11610 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 G_MEMSTATUS] is
11620 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 disabled, then t
11630 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 he other.** meth
11640 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 ods must be thre
11650 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d adsafe or else m
11660 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 ake their own ar
11670 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a rangements for.*
11680 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e * serialization.
11690 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 .**.** SQLite wi
116a0 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 ll never invoke
116b0 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 xInit() more tha
116c0 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 n once without a
116d0 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a n intervening.**
116e0 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f call to xShutdo
116f0 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 wn()..*/.typedef
11700 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
11710 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 mem_methods sqli
11720 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b te3_mem_methods;
11730 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
11740 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 mem_methods {.
11750 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 void *(*xMalloc)
11760 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f (int); /
11770 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * Memory allocat
11780 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a ion function */.
11790 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 void (*xFree)(
117a0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 void*);
117b0 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 /* Free a prior
117c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
117d0 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f void *(*xReallo
117e0 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 c)(void*,int);
117f0 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c /* Resize an all
11800 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 ocation */. int
11810 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 (*xSize)(void*)
11820 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 ; /* R
11830 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f eturn the size o
11840 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 f an allocation
11850 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e */. int (*xRoun
11860 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 dup)(int);
11870 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 /* Round up
11880 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 request size to
11890 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 allocation size
118a0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 */. int (*xInit
118b0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
118c0 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a /* Initializ
118d0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
118e0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 ocator */. void
118f0 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f (*xShutdown)(vo
11900 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 id*); /* De
11910 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d initialize the m
11920 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
11930 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
11940 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 ata;
11950 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 /* Argument
11960 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 to xInit() and x
11970 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b Shutdown() */.};
11980 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
11990 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 : Configuration
119a0 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f Options.** KEYWO
119b0 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 RDS: {configurat
119c0 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a ion option}.**.*
119d0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
119e0 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 s are the availa
119f0 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 ble integer conf
11a00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
11a10 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 s that.** can be
11a20 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
11a30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
11a40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
11a50 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
11a60 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e e..**.** New con
11a70 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
11a80 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ns may be added
11a90 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
11aa0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
11ab0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 Existing config
11ac0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
11ad0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 might be discont
11ae0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 inued. Applicat
11af0 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 ions.** should c
11b00 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
11b10 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 code from [sqlit
11b20 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 e3_config()] to
11b30 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a make sure that.*
11b40 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 * the call worke
11b50 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 d. The [sqlite3
11b60 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
11b70 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e face will return
11b80 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b a.** non-zero [
11b90 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 error code] if a
11ba0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 discontinued or
11bb0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e unsupported con
11bc0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
11bd0 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e n.** is invoked.
11be0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b .**.** <dl>.** [
11bf0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
11c00 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 INGLETHREAD]] <d
11c10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
11c20 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 SINGLETHREAD</dt
11c30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
11c40 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
11c50 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
11c60 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
11c70 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
11c80 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 ding mode] to Si
11c90 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e ngle-thread. In
11ca0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 other words, it
11cb0 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c disables.** all
11cc0 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 mutexing and pu
11cd0 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 ts SQLite into a
11ce0 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 mode where it c
11cf0 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a an only be used.
11d00 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 ** by a single t
11d10 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c hread. ^If SQL
11d20 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
11d30 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
11d40 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
11d50 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
11d60 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
11d70 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
11d80 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 * it is not poss
11d90 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 ible to change t
11da0 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f he [threading mo
11db0 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 de] from its def
11dc0 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 ault.** value of
11dd0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 Single-thread a
11de0 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 nd so [sqlite3_c
11df0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 onfig()] will re
11e00 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 turn .** [SQLITE
11e10 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 _ERROR] if calle
11e20 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 d with the SQLIT
11e30 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
11e40 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 HREAD.** configu
11e50 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
11e60 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
11e70 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
11e80 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 HREAD]] <dt>SQLI
11e90 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
11ea0 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 HREAD</dt>.** <d
11eb0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 d>There are no a
11ec0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
11ed0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 option. ^This
11ee0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a option sets the.
11ef0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ** [threading mo
11f00 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 de] to Multi-thr
11f10 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 ead. In other w
11f20 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 ords, it disable
11f30 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e s.** mutexing on
11f40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
11f50 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 ction] and [prep
11f60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
11f70 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 objects..** The
11f80 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 application is r
11f90 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 esponsible for s
11fa0 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 erializing acces
11fb0 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 s to.** [databas
11fc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 e connections] a
11fd0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
11fe0 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f tements]. But o
11ff0 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 ther mutexes.**
12000 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 are enabled so t
12010 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
12020 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 be safe to use i
12030 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 n a multi-thread
12040 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e ed.** environmen
12050 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 t as long as no
12060 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 two threads atte
12070 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 mpt to use the s
12080 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 ame.** [database
12090 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 connection] at
120a0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 the same time.
120b0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
120c0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
120d0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
120e0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
120f0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
12100 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
12110 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e then.** it is n
12120 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 ot possible to s
12130 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 et the Multi-thr
12140 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d ead [threading m
12150 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ode] and.** [sql
12160 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
12170 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
12180 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c TE_ERROR] if cal
12190 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
121a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
121b0 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 LTITHREAD config
121c0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c uration option.<
121d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
121e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
121f0 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 LIZED]] <dt>SQLI
12200 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
12210 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 IZED</dt>.** <dd
12220 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
12230 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
12240 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f option. ^This o
12250 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
12260 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 * [threading mod
12270 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 e] to Serialized
12280 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 . In other words
12290 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e , this option en
122a0 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 ables.** all mut
122b0 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 exes including t
122c0 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 he recursive.**
122d0 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 mutexes on [data
122e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
122f0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
12300 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 tatement] object
12310 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f s..** In this mo
12320 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 de (which is the
12330 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 default when SQ
12340 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
12350 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 with.** [SQLITE
12360 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 _THREADSAFE=1])
12370 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
12380 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 ry will itself s
12390 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a erialize access.
123a0 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 ** to [database
123b0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 connections] and
123c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
123d0 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 ments] so that t
123e0 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f he.** applicatio
123f0 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 n is free to use
12400 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
12410 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
12420 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b or the.** same [
12430 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
12440 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 nt] in different
12450 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 threads at the
12460 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 same time..** ^I
12470 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
12480 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
12490 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
124a0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
124b0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
124c0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
124d0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 hen.** it is not
124e0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 possible to set
124f0 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 the Serialized
12500 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
12510 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
12520 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 _config()] will
12530 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
12540 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 RROR] if called
12550 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 with the.** SQLI
12560 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
12570 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 IZED configurati
12580 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a on option.</dd>.
12590 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
125a0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c ONFIG_MALLOC]] <
125b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
125c0 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 _MALLOC</dt>.**
125d0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 <dd> ^(The SQLIT
125e0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 E_CONFIG_MALLOC
125f0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
12600 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
12610 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f hich is .** a po
12620 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
12630 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
12640 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
12650 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 ] structure..**
12660 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 The argument spe
12670 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e cifies.** altern
12680 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 ative low-level
12690 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
126a0 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 n routines to be
126b0 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f used in place o
126c0 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 f.** the memory
126d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
126e0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 nes built into S
126f0 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 QLite.)^ ^SQLite
12700 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 makes.** its ow
12710 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f n private copy o
12720 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 f the content of
12730 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 the [sqlite3_me
12740 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 m_methods] struc
12750 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 ture.** before t
12760 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 he [sqlite3_conf
12770 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 ig()] call retur
12780 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ns.</dd>.**.** [
12790 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
127a0 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 ETMALLOC]] <dt>S
127b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
127c0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
127d0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 dd> ^(The SQLITE
127e0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
127f0 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 C option takes a
12800 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
12810 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 which.** is a p
12820 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
12830 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 tance of the [sq
12840 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
12850 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a s] structure..**
12860 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 The [sqlite3_me
12870 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 m_methods].** st
12880 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 ructure is fille
12890 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 d with the curre
128a0 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d ntly defined mem
128b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
128c0 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 outines.)^.** Th
128d0 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 is option can be
128e0 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 used to overloa
128f0 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 d the default me
12900 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
12910 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 ** routines with
12920 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 a wrapper that
12930 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f simulations memo
12940 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
12950 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 ilure or.** trac
12960 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c ks memory usage,
12970 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f for example. </
12980 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
12990 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
129a0 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 TUS]] <dt>SQLITE
129b0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
129c0 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e S</dt>.** <dd> ^
129d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
129e0 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 G_MEMSTATUS opti
129f0 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 on takes single
12a00 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 argument of type
12a10 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 int,.** interpr
12a20 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 eted as a boolea
12a30 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 n, which enables
12a40 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 or disables the
12a50 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a collection of.*
12a60 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
12a70 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 ion statistics.
12a80 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c ^(When memory al
12a90 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 location statist
12aa0 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 ics are.** disab
12ab0 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 led, the followi
12ac0 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ng SQLite interf
12ad0 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d aces become non-
12ae0 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 operational:.**
12af0 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e <ul>.** <li>
12b00 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
12b10 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c _used()].** <l
12b20 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f i> [sqlite3_memo
12b30 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a ry_highwater()].
12b40 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
12b50 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
12b60 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 it64()].** <li
12b70 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 > [sqlite3_statu
12b80 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c s64()].** </ul
12b90 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 >)^.** ^Memory a
12ba0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 llocation statis
12bb0 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 tics are enabled
12bc0 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 by default unle
12bd0 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 ss SQLite is.**
12be0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 compiled with [S
12bf0 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 QLITE_DEFAULT_ME
12c00 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 MSTATUS]=0 in wh
12c10 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a ich case memory.
12c20 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 ** allocation st
12c30 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 atistics are dis
12c40 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
12c50 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
12c60 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
12c70 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 _SCRATCH]] <dt>S
12c80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
12c90 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATCH</dt>.** <dd
12ca0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f > ^The SQLITE_CO
12cb0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 NFIG_SCRATCH opt
12cc0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
12cd0 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
12ce0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c ffer.** that SQL
12cf0 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 ite can use for
12d00 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 scratch memory.
12d10 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 ^(There are thr
12d20 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 ee arguments.**
12d30 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 to SQLITE_CONFIG
12d40 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 _SCRATCH: A poi
12d50 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a nter an 8-byte.*
12d60 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 * aligned memory
12d70 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 buffer from whi
12d80 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 ch the scratch a
12d90 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 llocations will
12da0 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 be.** drawn, the
12db0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 size of each sc
12dc0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e ratch allocation
12dd0 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 (sz),.** and th
12de0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
12df0 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f of scratch allo
12e00 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a cations (N).)^.*
12e10 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
12e20 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 ment must be a p
12e30 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 ointer to an 8-b
12e40 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 yte aligned buff
12e50 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 er.** of at leas
12e60 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
12e70 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 memory..** ^SQLi
12e80 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 te will not use
12e90 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 more than one sc
12ea0 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 ratch buffers pe
12eb0 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 r thread..** ^SQ
12ec0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 Lite will never
12ed0 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 request a scratc
12ee0 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 h buffer that is
12ef0 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 more than 6.**
12f00 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 times the databa
12f10 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a se page size..**
12f20 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 ^If SQLite need
12f30 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e s needs addition
12f40 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 al.** scratch me
12f50 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 mory beyond what
12f60 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 is provided by
12f70 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 this configurati
12f80 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 on option, then
12f90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
12fa0 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 loc()] will be u
12fb0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 sed to obtain th
12fc0 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e e memory needed.
12fd0 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 <p>.** ^When the
12fe0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f application pro
12ff0 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 vides any amount
13000 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f of scratch memo
13010 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 ry using.** SQLI
13020 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
13030 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 H, SQLite avoids
13040 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 unnecessary lar
13050 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d ge.** [sqlite3_m
13060 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 alloc|heap alloc
13070 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 ations]..** This
13080 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f can help [Robso
13090 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 n proof|prevent
130a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
130b0 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 n failures] due
130c0 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d to heap.** fragm
130d0 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d entation in low-
130e0 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 memory embedded
130f0 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 systems..** </dd
13100 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
13110 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
13120 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 E]] <dt>SQLITE_C
13130 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c ONFIG_PAGECACHE<
13140 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
13150 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
13160 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e PAGECACHE option
13170 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
13180 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
13190 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 r.** that SQLite
131a0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 can use for the
131b0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 database page c
131c0 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 ache with the de
131d0 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 fault page.** ca
131e0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
131f0 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f on. .** This co
13200 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 nfiguration shou
13210 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 ld not be used i
13220 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
13230 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 -define page.**
13240 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
13250 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 tion is loaded u
13260 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
13270 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d _CONFIG_PCACHE2]
13280 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f .** configuratio
13290 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 n option..** ^Th
132a0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
132b0 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 guments to SQLIT
132c0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
132d0 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f HE: A pointer to
132e0 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e .** 8-byte align
132f0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 ed.** memory, th
13300 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 e size of each p
13310 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c age buffer (sz),
13320 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 and the number
13330 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a of pages (N)..**
13340 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 The sz argument
13350 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 should be the s
13360 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 ize of the large
13370 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 st database page
13380 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 .** (a power of
13390 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 two between 512
133a0 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 and 65536) plus
133b0 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 some extra bytes
133c0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 for each.** pag
133d0 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 e header. ^The
133e0 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 number of extra
133f0 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 bytes needed by
13400 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a the page header.
13410 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d ** can be determ
13420 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b ined using the [
13430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
13440 41 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 ACHE_HDRSZ] opti
13450 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 on .** to [sqlit
13460 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a e3_config()]..**
13470 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 ^It is harmless
13480 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 , apart from the
13490 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a wasted memory,.
134a0 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 ** for the sz pa
134b0 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 rameter to be la
134c0 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 rger than necess
134d0 61 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a ary. The first.
134e0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 ** argument shou
134f0 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e ld pointer to an
13500 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 8-byte aligned
13510 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 block of memory
13520 74 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 that.** is at le
13530 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f ast sz*N bytes o
13540 66 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 f memory, otherw
13550 69 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62 ise subsequent b
13560 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e ehavior is.** un
13570 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c defined..** ^SQL
13580 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 ite will use the
13590 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 memory provided
135a0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 by the first ar
135b0 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 gument to satisf
135c0 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 y its.** memory
135d0 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 needs for the fi
135e0 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 rst N pages that
135f0 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 it adds to cach
13600 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e e. ^If addition
13610 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 al.** page cache
13620 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 memory is neede
13630 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 d beyond what is
13640 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 provided by thi
13650 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a s option, then.*
13660 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f * SQLite goes to
13670 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
13680 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 ()] for the addi
13690 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 tional storage s
136a0 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a pace.</dd>.**.**
136b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
136c0 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 _HEAP]] <dt>SQLI
136d0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f TE_CONFIG_HEAP</
136e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 dt>.** <dd> ^The
136f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 SQLITE_CONFIG_H
13700 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 EAP option speci
13710 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
13720 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 mory buffer .**
13730 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
13740 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 use for all of
13750 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f its dynamic memo
13760 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
13770 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 eds.** beyond th
13780 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 ose provided for
13790 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 by [SQLITE_CONF
137a0 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a IG_SCRATCH] and.
137b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
137c0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a G_PAGECACHE]..**
137d0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^The SQLITE_CON
137e0 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 FIG_HEAP option
137f0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c is only availabl
13800 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 e if SQLite is c
13810 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 ompiled.** with
13820 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 either [SQLITE_E
13830 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f NABLE_MEMSYS3] o
13840 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 r [SQLITE_ENABLE
13850 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 _MEMSYS5] and re
13860 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 turns.** [SQLITE
13870 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b _ERROR] if invok
13880 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a ed otherwise..**
13890 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 ^There are thre
138a0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 e arguments to S
138b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
138c0 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 P:.** An 8-byte
138d0 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 aligned pointer
138e0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a to the memory,.*
138f0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
13900 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d bytes in the mem
13910 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 ory buffer, and
13920 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f the minimum allo
13930 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 cation size..**
13940 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f ^If the first po
13950 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 inter (the memor
13960 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 y pointer) is NU
13970 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 LL, then SQLite
13980 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 reverts.** to us
13990 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 ing its default
139a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
139b0 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c (the system mal
139c0 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 loc() implementa
139d0 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e tion),.** undoin
139e0 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f g any prior invo
139f0 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 cation of [SQLIT
13a00 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
13a10 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 . ^If the.** me
13a20 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 mory pointer is
13a30 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 not NULL then th
13a40 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 e alternative me
13a50 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
13a60 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 r is engaged to
13a70 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 handle all of SQ
13a80 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c Lites memory all
13a90 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a ocation needs..*
13aa0 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e * The first poin
13ab0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 ter (the memory
13ac0 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 pointer) must be
13ad0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 aligned to an 8
13ae0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 -byte.** boundar
13af0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 y or subsequent
13b00 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 behavior of SQLi
13b10 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 te will be undef
13b20 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e ined..** The min
13b30 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 imum allocation
13b40 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 size is capped a
13b50 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 t 2**12. Reasona
13b60 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f ble values.** fo
13b70 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c r the minimum al
13b80 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 location size ar
13b90 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 e 2**5 through 2
13ba0 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 **8.</dd>.**.**
13bb0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
13bc0 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 MUTEX]] <dt>SQLI
13bd0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c TE_CONFIG_MUTEX<
13be0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
13bf0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
13c00 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 _MUTEX option ta
13c10 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
13c20 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
13c30 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 .** pointer to a
13c40 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
13c50 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
13c60 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
13c70 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 ure..** The argu
13c80 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 ment specifies a
13c90 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c lternative low-l
13ca0 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 evel mutex routi
13cb0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a nes to be used.*
13cc0 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d * in place the m
13cd0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 utex routines bu
13ce0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e ilt into SQLite.
13cf0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 )^ ^SQLite make
13d00 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 s a copy of.** t
13d10 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
13d20 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
13d30 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
13d40 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 ure before the c
13d50 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
13d60 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 e3_config()] ret
13d70 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 urns. ^If SQLite
13d80 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
13d90 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
13da0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
13db0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
13dc0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
13dd0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 option then.** t
13de0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 he entire mutexi
13df0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 ng subsystem is
13e00 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 omitted from the
13e10 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 build and hence
13e20 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 calls to.** [sq
13e30 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
13e40 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
13e50 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e CONFIG_MUTEX con
13e60 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
13e70 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e n will.** return
13e80 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e [SQLITE_ERROR].
13e90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
13ea0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
13eb0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 UTEX]] <dt>SQLIT
13ec0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
13ed0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e X</dt>.** <dd> ^
13ee0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
13ef0 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 IG_GETMUTEX opti
13f00 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
13f10 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
13f20 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 .** is a pointer
13f30 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
13f40 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
13f50 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
13f60 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a tructure. The.*
13f70 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 * [sqlite3_mutex
13f80 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
13f90 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
13fa0 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
13fb0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 tly defined mute
13fc0 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a x routines.)^.**
13fd0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
13fe0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
13ff0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
14000 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f mutex allocatio
14010 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 n.** routines wi
14020 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 th a wrapper use
14030 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 d to track mutex
14040 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f usage for perfo
14050 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c rmance.** profil
14060 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 ing or testing,
14070 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e for example. ^
14080 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
14090 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
140a0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
140b0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
140c0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
140d0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
140e0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 then.** the enti
140f0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 re mutexing subs
14100 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 ystem is omitted
14110 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 from the build
14120 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 and hence calls
14130 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
14140 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 onfig()] with th
14150 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
14160 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 GETMUTEX configu
14170 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 ration option wi
14180 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
14190 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 LITE_ERROR].</dd
141a0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
141b0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
141c0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 E]] <dt>SQLITE_C
141d0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c ONFIG_LOOKASIDE<
141e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
141f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
14200 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f _LOOKASIDE optio
14210 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 n takes two argu
14220 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 ments that deter
14230 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 mine.** the defa
14240 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b ult size of look
14250 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 aside memory on
14260 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 each [database c
14270 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 onnection]..** T
14280 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
14290 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 t is the.** size
142a0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 of each lookasi
142b0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 de buffer slot a
142c0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 nd the second is
142d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
142e0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 * slots allocate
142f0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 d to each databa
14300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e se connection.)^
14310 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ^(SQLITE_CONFI
14320 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 G_LOOKASIDE.** s
14330 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 ets the <i>defau
14340 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 lt</i> lookaside
14350 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 size. The [SQLI
14360 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
14370 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e ASIDE].** option
14380 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f to [sqlite3_db_
14390 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 config()] can be
143a0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 used to change
143b0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a the lookaside.**
143c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
143d0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e n individual con
143e0 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 nections.)^ </dd
143f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
14400 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d _CONFIG_PCACHE2]
14410 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
14420 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e FIG_PCACHE2</dt>
14430 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
14440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
14450 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 CHE2 option take
14460 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
14470 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a ent which is .**
14480 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
14490 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
144a0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 _methods2] objec
144b0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 t. This object
144c0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 specifies.** the
144d0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 interface to a
144e0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 custom page cach
144f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
14500 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d .)^.** ^SQLite m
14510 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 akes a copy of t
14520 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 he [sqlite3_pcac
14530 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a he_methods2] obj
14540 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ect.</dd>.**.**
14550 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
14560 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 GETPCACHE2]] <dt
14570 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
14580 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a ETPCACHE2</dt>.*
14590 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
145a0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
145b0 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b ACHE2 option tak
145c0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
145d0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 ment which.** is
145e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
145f0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
14600 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 _methods2] objec
14610 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 t. SQLite copie
14620 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 s of.** the curr
14630 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 ent page cache i
14640 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e mplementation in
14650 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 to that object.)
14660 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b ^ </dd>.**.** [[
14670 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
14680 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 G]] <dt>SQLITE_C
14690 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a ONFIG_LOG</dt>.*
146a0 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 * <dd> The SQLIT
146b0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 E_CONFIG_LOG opt
146c0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 ion is used to c
146d0 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c onfigure the SQL
146e0 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 ite.** global [e
146f0 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e rror log]..** (^
14700 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
14710 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b G_LOG option tak
14720 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 es two arguments
14730 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 : a pointer to a
14740 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 .** function wit
14750 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 h a call signatu
14760 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f re of void(*)(vo
14770 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 id*,int,const ch
14780 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 ar*), .** and a
14790 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e pointer to void.
147a0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f ^If the functio
147b0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 n pointer is not
147c0 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 NULL, it is.**
147d0 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 invoked by [sqli
147e0 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 te3_log()] to pr
147f0 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 ocess each loggi
14800 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 ng event. ^If t
14810 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 he.** function p
14820 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 ointer is NULL,
14830 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 the [sqlite3_log
14840 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 ()] interface be
14850 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a comes a no-op..*
14860 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e * ^The void poin
14870 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 ter that is the
14880 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
14890 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 to SQLITE_CONFIG
148a0 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 _LOG is.** passe
148b0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 d through as the
148c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
148d0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 to the applicat
148e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 ion-defined logg
148f0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 er.** function w
14900 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e henever that fun
14910 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 ction is invoked
14920 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 . ^The second p
14930 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 arameter to.** t
14940 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 he logger functi
14950 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 on is a copy of
14960 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
14970 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 ter to the corre
14980 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c sponding.** [sql
14990 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c ite3_log()] call
149a0 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 and is intended
149b0 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 to be a [result
149c0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 code] or an.**
149d0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
149e0 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 code]. ^The th
149f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 ird parameter pa
14a00 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 ssed to the logg
14a10 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 er is.** log mes
14a20 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 sage after forma
14a30 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 tting via [sqlit
14a40 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a e3_snprintf()]..
14a50 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f ** The SQLite lo
14a60 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 gging interface
14a70 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 is not reentrant
14a80 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e ; the logger fun
14a90 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 ction.** supplie
14aa0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 d by the applica
14ab0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e tion must not in
14ac0 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 voke any SQLite
14ad0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e interface..** In
14ae0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 a multi-threade
14af0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 d application, t
14b00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
14b10 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a efined logger.**
14b20 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 function must b
14b30 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f e threadsafe. </
14b40 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
14b50 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 TE_CONFIG_URI]]
14b60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
14b70 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 G_URI.** <dd>^(T
14b80 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
14b90 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 _URI option take
14ba0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
14bb0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e ent of type int.
14bc0 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c .** If non-zero,
14bd0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 then URI handli
14be0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 ng is globally e
14bf0 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 nabled. If the p
14c00 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f arameter is zero
14c10 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 ,.** then URI ha
14c20 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c ndling is global
14c30 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e ly disabled.)^ ^
14c40 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 If URI handling
14c50 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 is globally.** e
14c60 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 nabled, all file
14c70 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 names passed to
14c80 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
14c90 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f , [sqlite3_open_
14ca0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 v2()],.** [sqlit
14cb0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a e3_open16()] or.
14cc0 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 ** specified as
14cd0 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d part of [ATTACH]
14ce0 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e commands are in
14cf0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 terpreted as URI
14d00 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a s, regardless.**
14d10 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
14d20 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f ot the [SQLITE_O
14d30 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 PEN_URI] flag is
14d40 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 set when the da
14d50 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
14d60 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 tion is opened.
14d70 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c ^If it is global
14d80 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c ly disabled, fil
14d90 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e enames are.** on
14da0 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 ly interpreted a
14db0 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 s URIs if the SQ
14dc0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c LITE_OPEN_URI fl
14dd0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 ag is set when t
14de0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 he.** database c
14df0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 onnection is ope
14e00 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c ned. ^(By defaul
14e10 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 t, URI handling
14e20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 is globally.** d
14e30 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 isabled. The def
14e40 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 ault value may b
14e50 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d e changed by com
14e60 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a piling with the.
14e70 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 ** [SQLITE_USE_U
14e80 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e RI] symbol defin
14e90 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 ed.)^.**.** [[SQ
14ea0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 LITE_CONFIG_COVE
14eb0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d RING_INDEX_SCAN]
14ec0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
14ed0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 FIG_COVERING_IND
14ee0 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e EX_SCAN.** <dd>^
14ef0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
14f00 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 G_COVERING_INDEX
14f10 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b _SCAN option tak
14f20 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 es a single inte
14f30 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ger.** argument
14f40 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 which is interpr
14f50 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 eted as a boolea
14f60 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e n in order to en
14f70 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a able or disable.
14f80 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f ** the use of co
14f90 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 vering indices f
14fa0 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 or full table sc
14fb0 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 ans in the query
14fc0 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e optimizer..** ^
14fd0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 The default sett
14fe0 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 ing is determine
14ff0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c d.** by the [SQL
15000 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 ITE_ALLOW_COVERI
15010 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 NG_INDEX_SCAN] c
15020 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
15030 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a on, or is "on".*
15040 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c * if that compil
15050 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 e-time option is
15060 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 omitted..** The
15070 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 ability to disa
15080 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 ble the use of c
15090 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 overing indices
150a0 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 for full table s
150b0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 cans.** is becau
150c0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 se some incorrec
150d0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 tly coded legacy
150e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 applications mi
150f0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a ght malfunction.
15100 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 ** when the opti
15110 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 mization is enab
15120 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 led. Providing
15130 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a the ability to.*
15140 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 * disable the op
15150 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 timization allow
15160 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 s the older, bug
15170 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 gy application c
15180 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 ode to work.** w
15190 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 ithout change ev
151a0 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 en with newer ve
151b0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
151c0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ..**.** [[SQLITE
151d0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d _CONFIG_PCACHE]]
151e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
151f0 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 _GETPCACHE]].**
15200 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
15210 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c G_PCACHE and SQL
15220 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
15230 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 ACHE.** <dd> The
15240 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f se options are o
15250 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 bsolete and shou
15260 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 ld not be used b
15270 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 y new code..** T
15280 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 hey are retained
15290 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 for backwards c
152a0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 ompatibility but
152b0 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e are now no-ops.
152c0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
152d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
152e0 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e SQLLOG]].** <dt>
152f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 SQLITE_CONFIG_SQ
15300 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 LLOG.** <dd>This
15310 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 option is only
15320 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c available if sql
15330 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
15340 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c with the.** [SQL
15350 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f ITE_ENABLE_SQLLO
15360 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 G] pre-processor
15370 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 macro defined.
15380 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
15390 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 nt should.** be
153a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 a pointer to a f
153b0 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 unction of type
153c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
153d0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 lite3*,const cha
153e0 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 r*, int)..** The
153f0 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 second should b
15400 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a e of type (void*
15410 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 ). The callback
15420 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 is invoked by th
15430 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 e library.** in
15440 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 three separate c
15450 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 ircumstances, id
15460 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 entified by the
15470 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
15480 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 the.** fourth pa
15490 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 rameter. If the
154a0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
154b0 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 is 0, then the
154c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
154d0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 ion.** passed as
154e0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
154f0 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 ment has just be
15500 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 en opened. The t
15510 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a hird argument.**
15520 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 points to a buf
15530 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 fer containing t
15540 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d he name of the m
15550 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c ain database fil
15560 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 e. If the.** fou
15570 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
15580 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 1, then the SQL
15590 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
155a0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
155b0 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f ter.** points to
155c0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 has just been e
155d0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 xecuted. Or, if
155e0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
155f0 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a eter is 2, then.
15600 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f ** the connectio
15610 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 n being passed a
15620 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
15630 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 ameter is being
15640 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 closed. The.** t
15650 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 hird parameter i
15660 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e s passed NULL In
15670 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 this case. An
15680 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 example of using
15690 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 this.** configu
156a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 ration option ca
156b0 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 n be seen in the
156c0 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 "test_sqllog.c"
156d0 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a source file in.
156e0 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c ** the canonical
156f0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 SQLite source t
15700 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ree.</dd>.**.**
15710 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
15720 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c MMAP_SIZE]].** <
15730 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
15740 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 _MMAP_SIZE.** <d
15750 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 d>^SQLITE_CONFIG
15760 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 _MMAP_SIZE takes
15770 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 two 64-bit inte
15780 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 ger (sqlite3_int
15790 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 64) values.** th
157a0 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 at are the defau
157b0 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d lt mmap size lim
157c0 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 it (the default
157d0 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b setting for.** [
157e0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 PRAGMA mmap_size
157f0 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d ]) and the maxim
15800 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 um allowed mmap
15810 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e size limit..** ^
15820 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 The default sett
15830 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 ing can be overr
15840 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 idden by each da
15850 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
15860 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 n using.** eithe
15870 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d r the [PRAGMA mm
15880 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 ap_size] command
15890 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 , or by using th
158a0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e e.** [SQLITE_FCN
158b0 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 TL_MMAP_SIZE] fi
158c0 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 le control. ^(T
158d0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 he maximum allow
158e0 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 ed mmap size.**
158f0 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 will be silently
15900 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 truncated if ne
15910 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 cessary so that
15920 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 it does not exce
15930 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c ed the.** compil
15940 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d e-time maximum m
15950 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 map size set by
15960 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d the.** [SQLITE_M
15970 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f AX_MMAP_SIZE] co
15980 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
15990 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 n.)^.** ^If eith
159a0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 er argument to t
159b0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 his option is ne
159c0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 gative, then tha
159d0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a t argument is.**
159e0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 changed to its
159f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 compile-time def
15a00 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 ault..**.** [[SQ
15a10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 LITE_CONFIG_WIN3
15a20 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 2_HEAPSIZE]].**
15a30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
15a40 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 G_WIN32_HEAPSIZE
15a50 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c .** <dd>^The SQL
15a60 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 ITE_CONFIG_WIN32
15a70 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e _HEAPSIZE option
15a80 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 is only availab
15a90 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a le if SQLite is.
15aa0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 ** compiled for
15ab0 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 Windows with the
15ac0 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d [SQLITE_WIN32_M
15ad0 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 ALLOC] pre-proce
15ae0 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 ssor macro.** de
15af0 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 fined. ^SQLITE_C
15b00 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 ONFIG_WIN32_HEAP
15b10 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d SIZE takes a 32-
15b20 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 bit unsigned int
15b30 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 eger value.** th
15b40 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 at specifies the
15b50 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 maximum size of
15b60 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 the created hea
15b70 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 p..**.** [[SQLIT
15b80 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f E_CONFIG_PCACHE_
15b90 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 HDRSZ]].** <dt>S
15ba0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
15bb0 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 CHE_HDRSZ.** <dd
15bc0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e >^The SQLITE_CON
15bd0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a FIG_PCACHE_HDRSZ
15be0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
15bf0 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 single parameter
15c00 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 which.** is a p
15c10 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
15c20 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 eger and writes
15c30 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 into that intege
15c40 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 r the number of
15c50 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 extra.** bytes p
15c60 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 er page required
15c70 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 for each page i
15c80 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 n [SQLITE_CONFIG
15c90 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 _PAGECACHE]..**
15ca0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 The amount of ex
15cb0 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 tra space requir
15cc0 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 ed can change de
15cd0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 pending on the c
15ce0 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 ompiler,.** targ
15cf0 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 et platform, and
15d00 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e SQLite version.
15d10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
15d20 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a CONFIG_PMASZ]].*
15d30 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
15d40 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 FIG_PMASZ.** <dd
15d50 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e >^The SQLITE_CON
15d60 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e FIG_PMASZ option
15d70 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
15d80 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a parameter which.
15d90 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 ** is an unsigne
15da0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 d integer and se
15db0 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 ts the "Minimum
15dc0 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 PMA Size" for th
15dd0 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a e multithreaded.
15de0 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 ** sorter to tha
15df0 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 t integer. The
15e00 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 default minimum
15e10 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 PMA Size is set
15e20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 by the.** [SQLIT
15e30 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 E_SORTER_PMASZ]
15e40 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
15e50 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 ion. New thread
15e60 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a s are launched.*
15e70 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 * to help with s
15e80 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 ort operations w
15e90 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 hen multithreade
15ea0 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 d sorting.** is
15eb0 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 enabled (using t
15ec0 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 he [PRAGMA threa
15ed0 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 ds] command) and
15ee0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 the amount of c
15ef0 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 ontent.** to be
15f00 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 sorted exceeds t
15f10 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d he page size tim
15f20 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f es the minimum o
15f30 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 f the.** [PRAGMA
15f40 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 cache_size] set
15f50 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 ting and this va
15f60 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f lue..** </dl>.*/
15f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
15f80 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
15f90 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a EAD 1 /* nil *
15fa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
15fb0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
15fc0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 EAD 2 /* nil
15fd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15fe0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
15ff0 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c ZED 3 /* nil
16000 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16010 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
16020 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 4 /* sq
16030 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
16040 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
16050 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
16060 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 ALLOC 5 /*
16070 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
16080 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
16090 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
160a0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f RATCH 6 /
160b0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c * void*, int sz,
160c0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e int N */.#defin
160d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
160e0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 PAGECACHE 7
160f0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 /* void*, int s
16100 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 z, int N */.#def
16110 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
16120 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 G_HEAP
16130 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 8 /* void*, int
16140 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 nByte, int min
16150 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16160 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
16170 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f US 9 /* boo
16180 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 lean */.#define
16190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
161a0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f TEX 10 /
161b0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
161c0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
161d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
161e0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 G_GETMUTEX 1
161f0 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 1 /* sqlite3_mu
16200 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a tex_methods* */.
16210 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 /* previously SQ
16220 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e LITE_CONFIG_CHUN
16230 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 KALLOC 12 which
16240 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a is now unused. *
16250 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 / .#define SQLIT
16260 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
16270 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 DE 13 /* int
16280 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
16290 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
162a0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f ACHE 14 /
162b0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 * no-op */.#defi
162c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
162d0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 _GETPCACHE 15
162e0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 /* no-op */.#d
162f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
16300 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 FIG_LOG
16310 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 16 /* xFunc, v
16320 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 oid* */.#define
16330 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
16340 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f I 17 /
16350 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 * int */.#define
16360 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
16370 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 CACHE2 18
16380 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 /* sqlite3_pcach
16390 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 e_methods2* */.#
163a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
163b0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 NFIG_GETPCACHE2
163c0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 19 /* sqlite3
163d0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 _pcache_methods2
163e0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
163f0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
16400 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 ING_INDEX_SCAN 2
16410 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 0 /* int */.#de
16420 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16430 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 IG_SQLLOG
16440 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 21 /* xSqllog,
16450 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 void* */.#define
16460 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
16470 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 MAP_SIZE 22
16480 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 /* sqlite3_int64
16490 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
164a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
164b0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 E_CONFIG_WIN32_H
164c0 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 EAPSIZE 23
164d0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f /* int nByte */
164e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
164f0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 CONFIG_PCACHE_HD
16500 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f RSZ 24 /
16510 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 * int *psz */.#d
16520 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
16530 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 FIG_PMASZ
16540 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 25 /* u
16550 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d nsigned int szPm
16560 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 a */../*.** CAPI
16570 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
16580 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 onnection Config
16590 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a uration Options.
165a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
165b0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
165c0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
165d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
165e0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
165f0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
16600 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
16610 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 nt to the [sqlit
16620 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
16630 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
16640 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 New configurati
16650 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 on options may b
16660 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
16670 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
16680 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e Lite..** Existin
16690 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 g configuration
166a0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 options might be
166b0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 discontinued.
166c0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 Applications.**
166d0 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 should check the
166e0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f return code fro
166f0 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f m [sqlite3_db_co
16700 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 nfig()] to make
16710 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 sure that.** the
16720 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e call worked. ^
16730 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f The [sqlite3_db_
16740 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
16750 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
16760 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
16770 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
16780 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
16790 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
167a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
167b0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
167c0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
167d0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
167e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e G_LOOKASIDE</dt>
167f0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
16800 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 ption takes thre
16810 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 e additional arg
16820 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 uments that dete
16830 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c rmine the .** [l
16840 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
16850 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 allocator] confi
16860 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 guration for the
16870 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
16880 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 ction]..** ^The
16890 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 first argument (
168a0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
168b0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
168c0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 db_config()] is
168d0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 a.** pointer to
168e0 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 a memory buffer
168f0 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 to use for looka
16900 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 side memory..**
16910 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
16920 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 ent after the SQ
16930 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
16940 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 OKASIDE verb.**
16950 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 may be NULL in w
16960 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 hich case SQLite
16970 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 will allocate t
16980 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 he.** lookaside
16990 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 buffer itself us
169a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c ing [sqlite3_mal
169b0 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 loc()]. ^The sec
169c0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
169d0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
169e0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 ach lookaside bu
169f0 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 ffer slot. ^The
16a00 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
16a10 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
16a20 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 .** slots. The
16a30 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 size of the buff
16a40 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 er in the first
16a50 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 argument must be
16a60 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a greater than.**
16a70 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 or equal to the
16a80 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 product of the
16a90 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 second and third
16aa0 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 arguments. The
16ab0 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 buffer.** must
16ac0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e be aligned to an
16ad0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 8-byte boundary
16ae0 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e . ^If the secon
16af0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
16b00 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
16b10 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f _LOOKASIDE is no
16b20 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 t a multiple of
16b30 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 8, it is interna
16b40 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 lly.** rounded d
16b50 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 own to the next
16b60 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 smaller multiple
16b70 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f of 8. ^(The lo
16b80 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a okaside memory.*
16b90 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
16ba0 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 for a database c
16bb0 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e onnection can on
16bc0 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 ly be changed wh
16bd0 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 en that.** conne
16be0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 ction is not cur
16bf0 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f rently using loo
16c00 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f kaside memory, o
16c10 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 r in other words
16c20 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 .** when the "cu
16c30 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 rrent value" ret
16c40 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
16c50 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 ite3_db_status](
16c60 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 D,[SQLITE_CONFIG
16c70 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 _LOOKASIDE],...)
16c80 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 is zero..** Any
16c90 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e attempt to chan
16ca0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 ge the lookaside
16cb0 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 memory configur
16cc0 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 ation when looka
16cd0 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 side.** memory i
16ce0 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 s in use leaves
16cf0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f the configuratio
16d00 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 n unchanged and
16d10 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c returns .** [SQL
16d20 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 ITE_BUSY].)^</dd
16d30 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
16d40 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
16d50 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 LE_FKEY</dt>.**
16d60 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
16d70 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 n is used to ena
16d80 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 ble or disable t
16d90 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f he enforcement o
16da0 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 f.** [foreign ke
16db0 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 y constraints].
16dc0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 There should be
16dd0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 two additional
16de0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 arguments..** Th
16df0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
16e00 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 is an integer w
16e10 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 hich is 0 to dis
16e20 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d able FK enforcem
16e30 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 ent,.** positive
16e40 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e to enable FK en
16e50 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 forcement or neg
16e60 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 ative to leave F
16e70 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a K enforcement.**
16e80 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 unchanged. The
16e90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
16ea0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 r is a pointer t
16eb0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 o an integer int
16ec0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 o which.** is wr
16ed0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 itten 0 or 1 to
16ee0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 indicate whether
16ef0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 FK enforcement
16f00 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 is off or on.**
16f10 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 following this c
16f20 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 all. The second
16f30 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
16f40 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 e a NULL pointer
16f50 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 , in.** which ca
16f60 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 se the FK enforc
16f70 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 ement setting is
16f80 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 not reported ba
16f90 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ck. </dd>.**.**
16fa0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
16fb0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 FIG_ENABLE_TRIGG
16fc0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 ER</dt>.** <dd>
16fd0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 ^This option is
16fe0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f used to enable o
16ff0 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 r disable [CREAT
17000 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 E TRIGGER | trig
17010 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 gers]..** There
17020 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 should be two ad
17030 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e ditional argumen
17040 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ts..** The first
17050 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 argument is an
17060 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 integer which is
17070 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 0 to disable tr
17080 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 iggers,.** posit
17090 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 ive to enable tr
170a0 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 iggers or negati
170b0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 ve to leave the
170c0 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 setting unchange
170d0 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 d..** The second
170e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
170f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
17100 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 teger into which
17110 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 .** is written 0
17120 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 or 1 to indicat
17130 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 e whether trigge
17140 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 rs are disabled
17150 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f or enabled.** fo
17160 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c llowing this cal
17170 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 l. The second p
17180 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 arameter may be
17190 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
171a0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 in.** which case
171b0 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 the trigger set
171c0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f ting is not repo
171d0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e rted back. </dd>
171e0 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a .**.** </dl>.*/.
171f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
17200 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
17210 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a E 1001 /*
17220 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a void* int int *
17230 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17240 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
17250 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 _FKEY 1002
17260 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 /* int int* */.#
17270 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
17280 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 CONFIG_ENABLE_TR
17290 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 IGGER 1003 /*
172a0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a int int* */.../*
172b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e .** CAPI3REF: En
172c0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
172d0 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 Extended Result
172e0 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a Codes.** METHOD:
172f0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
17300 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 The sqlite3_exte
17310 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
17320 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 s() routine enab
17330 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
17340 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 the.** [extended
17350 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 result codes] f
17360 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 eature of SQLite
17370 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 . ^The extended
17380 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 result.** codes
17390 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 are disabled by
173a0 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 default for hist
173b0 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 orical compatibi
173c0 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c lity..*/.int sql
173d0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
173e0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 sult_codes(sqlit
173f0 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b e3*, int onoff);
17400 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
17410 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f : Last Insert Ro
17420 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 wid.** METHOD: s
17430 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 qlite3.**.** ^Ea
17440 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 ch entry in most
17450 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 SQLite tables (
17460 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 except for [WITH
17470 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 OUT ROWID] table
17480 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 s).** has a uniq
17490 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 ue 64-bit signed
174a0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 .** integer key
174b0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 called the [ROWI
174c0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 D | "rowid"]. ^T
174d0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 he rowid is alwa
174e0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 ys available.**
174f0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 as an undeclared
17500 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f column named RO
17510 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f WID, OID, or _RO
17520 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 WID_ as long as
17530 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 those.** names a
17540 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 re not also used
17550 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 by explicitly d
17560 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e eclared columns.
17570 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c ^If.** the tabl
17580 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f e has a column o
17590 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 f type [INTEGER
175a0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 PRIMARY KEY] the
175b0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a n that column.**
175c0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 is another alia
175d0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e s for the rowid.
175e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
175f0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
17600 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 rowid(D) interfa
17610 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b ce returns the [
17620 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a rowid] of the .*
17630 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 * most recent su
17640 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
17650 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 ] into a rowid t
17660 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c able or [virtual
17670 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 table].** on da
17680 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
17690 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 n D..** ^Inserts
176a0 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 into [WITHOUT R
176b0 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 OWID] tables are
176c0 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a not recorded..*
176d0 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 * ^If no success
176e0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e ful [INSERT]s in
176f0 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a to rowid tables.
17700 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 ** have ever occ
17710 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 urred on the dat
17720 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
17730 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c D, .** then sql
17740 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
17750 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e _rowid(D) return
17760 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 s zero..**.** ^(
17770 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f If an [INSERT] o
17780 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 ccurs within a t
17790 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e rigger or within
177a0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c a [virtual tabl
177b0 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 e].** method, th
177c0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 en this routine
177d0 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 will return the
177e0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 [rowid] of the i
177f0 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 nserted.** row a
17800 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 s long as the tr
17810 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c igger or virtual
17820 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 table method is
17830 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 running..** But
17840 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 once the trigge
17850 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 r or virtual tab
17860 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 le method ends,
17870 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
17880 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 ed .** by this r
17890 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 outine reverts t
178a0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 o what it was be
178b0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 fore the trigger
178c0 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 or virtual.** t
178d0 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 able method bega
178e0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b n.)^.**.** ^An [
178f0 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 INSERT] that fai
17900 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 ls due to a cons
17910 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e traint violation
17920 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 is not a.** suc
17930 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
17940 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 and does not ch
17950 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 ange the value r
17960 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a eturned by this.
17970 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 ** routine. ^Th
17980 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 us INSERT OR FAI
17990 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e L, INSERT OR IGN
179a0 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 ORE, INSERT OR R
179b0 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 OLLBACK,.** and
179c0 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 INSERT OR ABORT
179d0 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 make no changes
179e0 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 to the return va
179f0 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 lue of this.** r
17a00 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 outine when thei
17a10 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c r insertion fail
17a20 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 s. ^(When INSER
17a30 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 T OR REPLACE.**
17a40 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e encounters a con
17a50 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f straint violatio
17a60 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 n, it does not f
17a70 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 ail. The.** INS
17a80 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f ERT continues to
17a90 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 completion afte
17aa0 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 r deleting rows
17ab0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 that caused.** t
17ac0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 he constraint pr
17ad0 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 oblem so INSERT
17ae0 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 OR REPLACE will
17af0 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a always change.**
17b00 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
17b10 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 e of this interf
17b20 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f ace.)^.**.** ^Fo
17b30 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f r the purposes o
17b40 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 f this routine,
17b50 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 an [INSERT] is c
17b60 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 onsidered to.**
17b70 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 be successful ev
17b80 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 en if it is subs
17b90 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 equently rolled
17ba0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 back..**.** This
17bb0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 function is acc
17bc0 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 essible to SQL s
17bd0 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 tatements via th
17be0 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 e.** [last_inser
17bf0 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 t_rowid() SQL fu
17c00 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 nction]..**.** I
17c10 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
17c20 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e ead performs a n
17c30 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 ew [INSERT] on t
17c40 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 he same.** datab
17c50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 ase connection w
17c60 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 hile the [sqlite
17c70 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
17c80 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 wid()].** functi
17c90 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e on is running an
17ca0 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 d thus changes t
17cb0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b he last insert [
17cc0 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 rowid],.** then
17cd0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
17ce0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c ed by [sqlite3_l
17cf0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
17d00 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 ()] is.** unpred
17d10 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 ictable and migh
17d20 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 t not equal eith
17d30 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 er the old or th
17d40 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e e new.** last in
17d50 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f sert [rowid]..*/
17d60 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
17d70 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
17d80 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 rt_rowid(sqlite3
17d90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
17da0 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e REF: Count The N
17db0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
17dc0 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 dified.** METHOD
17dd0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
17de0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 ^This function r
17df0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
17e00 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 r of rows modifi
17e10 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a ed, inserted or.
17e20 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 ** deleted by th
17e30 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 e most recently
17e40 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 completed INSERT
17e50 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
17e60 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 TE.** statement
17e70 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 on the database
17e80 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 connection speci
17e90 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 fied by the only
17ea0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e parameter..** ^
17eb0 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 Executing any ot
17ec0 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 her type of SQL
17ed0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e statement does n
17ee0 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 ot modify the va
17ef0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lue.** returned
17f00 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e by this function
17f10 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 ..**.** ^Only ch
17f20 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 anges made direc
17f30 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 tly by the INSER
17f40 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c T, UPDATE or DEL
17f50 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 ETE statement ar
17f60 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 e.** considered
17f70 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e - auxiliary chan
17f80 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 ges caused by [C
17f90 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 REATE TRIGGER |
17fa0 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b triggers], .** [
17fb0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 foreign key acti
17fc0 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 ons] or [REPLACE
17fd0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 ] constraint res
17fe0 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 olution are not
17ff0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 counted..** .**
18000 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 Changes to a vie
18010 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 w that are inter
18020 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 cepted by .** [I
18030 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 NSTEAD OF trigge
18040 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 r | INSTEAD OF t
18050 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 riggers] are not
18060 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 counted. ^The v
18070 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 alue .** returne
18080 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 d by sqlite3_cha
18090 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 nges() immediate
180a0 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 ly after an INSE
180b0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a RT, UPDATE or .*
180c0 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 * DELETE stateme
180d0 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 nt run on a view
180e0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e is always zero.
180f0 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 Only changes ma
18100 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 de to real .** t
18110 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 ables are counte
18120 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 d..**.** Things
18130 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 are more complic
18140 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 ated if the sqli
18150 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 te3_changes() fu
18160 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 nction is.** exe
18170 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 cuted while a tr
18180 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 igger program is
18190 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d running. This m
181a0 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 ay happen if the
181b0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 .** program uses
181c0 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 the [changes()
181d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f SQL function], o
181e0 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 r if some other
181f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 callback.** func
18200 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c tion invokes sql
18210 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 ite3_changes() d
18220 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 irectly. Essenti
18230 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c ally:.** .** <ul
18240 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 >.** <li> ^(Be
18250 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 fore entering a
18260 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 trigger program
18270 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
18280 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 ed by.**
18290 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
182a0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 ) function is sa
182b0 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 ved. After the t
182c0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a rigger program .
182d0 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 ** has fi
182e0 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 nished, the orig
182f0 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 inal value is re
18300 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a stored.)^.** .**
18310 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e <li> ^(Within
18320 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 a trigger progr
18330 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 am each INSERT,
18340 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 UPDATE and DELET
18350 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 E .** sta
18360 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 tement sets the
18370 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
18380 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 y sqlite3_change
18390 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 s() .** u
183a0 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 pon completion a
183b0 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 s normal. Of cou
183c0 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 rse, this value
183d0 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 will not include
183e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 .** any
183f0 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 changes performe
18400 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 d by sub-trigger
18410 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 s, as the sqlite
18420 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 3_changes() .**
18430 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c value wil
18440 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 l be saved and r
18450 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 estored after ea
18460 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 ch sub-trigger h
18470 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 as run.)^.** </u
18480 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 l>.** .** ^This
18490 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 means that if th
184a0 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 e changes() SQL
184b0 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d function (or sim
184c0 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a ilar) is used.**
184d0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e by the first IN
184e0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 SERT, UPDATE or
184f0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
18500 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 within a trigge
18510 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e r, it .** return
18520 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 s the value as s
18530 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c et when the call
18540 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 ing statement be
18550 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a gan executing..*
18560 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 * ^If it is used
18570 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f by the second o
18580 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 r subsequent suc
18590 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 h statement with
185a0 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a in a trigger .**
185b0 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 program, the va
185c0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 lue returned ref
185d0 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 lects the number
185e0 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 of rows modifie
185f0 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 d by the .** pre
18600 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 vious INSERT, UP
18610 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 DATE or DELETE s
18620 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 tatement within
18630 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 the same trigger
18640 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
18650 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f the [sqlite3_to
18660 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 tal_changes()] i
18670 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a nterface, the.**
18680 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 [count_changes
18690 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 pragma], and the
186a0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 [changes() SQL
186b0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
186c0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
186d0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e hread makes chan
186e0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ges on the same
186f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18700 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 ion.** while [sq
18710 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d lite3_changes()]
18720 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
18730 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
18740 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 ned.** is unpred
18750 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 ictable and not
18760 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 meaningful..*/.i
18770 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 nt sqlite3_chang
18780 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
18790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
187a0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 otal Number Of R
187b0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 ows Modified.**
187c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
187d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
187e0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
187f0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 total number of
18800 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 rows inserted,
18810 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 modified or.** d
18820 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 eleted by all [I
18830 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d NSERT], [UPDATE]
18840 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 or [DELETE] sta
18850 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 tements complete
18860 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 d.** since the d
18870 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
18880 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 on was opened, i
18890 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 ncluding those e
188a0 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 xecuted as.** pa
188b0 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 rt of trigger pr
188c0 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 ograms. ^Executi
188d0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 ng any other typ
188e0 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 e of SQL stateme
188f0 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 nt.** does not a
18900 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 ffect the value
18910 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
18920 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
18930 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 s()..** .** ^Cha
18940 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 nges made as par
18950 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 t of [foreign ke
18960 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 y actions] are i
18970 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a ncluded in the.*
18980 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f * count, but tho
18990 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 se made as part
189a0 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 of REPLACE const
189b0 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e raint resolution
189c0 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 are.** not. ^Ch
189d0 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 anges to a view
189e0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 that are interce
189f0 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 pted by INSTEAD
18a00 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 OF triggers .**
18a10 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e are not counted.
18a20 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f .** .** See also
18a30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 the [sqlite3_ch
18a40 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 anges()] interfa
18a50 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e ce, the.** [coun
18a60 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 t_changes pragma
18a70 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 ], and the [tota
18a80 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 l_changes() SQL
18a90 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
18aa0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
18ab0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e hread makes chan
18ac0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ges on the same
18ad0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18ae0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 ion.** while [sq
18af0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
18b00 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e ges()] is runnin
18b10 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 g then the value
18b20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 .** returned is
18b30 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
18b40 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c d not meaningful
18b50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
18b60 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 _total_changes(s
18b70 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
18b80 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 CAPI3REF: Inter
18b90 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e rupt A Long-Runn
18ba0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 ing Query.** MET
18bb0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
18bc0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
18bd0 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e n causes any pen
18be0 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 ding database op
18bf0 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 eration to abort
18c00 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 and.** return a
18c10 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f t its earliest o
18c20 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 pportunity. This
18c30 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 routine is typi
18c40 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 cally.** called
18c50 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 in response to a
18c60 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 user action suc
18c70 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 h as pressing "C
18c80 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 ancel".** or Ctr
18c90 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 l-C where the us
18ca0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 er wants a long
18cb0 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 query operation
18cc0 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 to halt.** immed
18cd0 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 iately..**.** ^I
18ce0 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c t is safe to cal
18cf0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 l this routine f
18d00 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 rom a thread dif
18d10 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a ferent from the.
18d20 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 ** thread that i
18d30 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e s currently runn
18d40 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 ing the database
18d50 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 operation. But
18d60 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 it.** is not sa
18d70 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 fe to call this
18d80 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b routine with a [
18d90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18da0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 ion] that.** is
18db0 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 closed or might
18dc0 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c close before sql
18dd0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
18de0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
18df0 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 ^If an SQL opera
18e00 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 tion is very nea
18e10 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 rly finished at
18e20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a the time when.**
18e30 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
18e40 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 pt() is called,
18e50 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f then it might no
18e60 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 t have an opport
18e70 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 unity.** to be i
18e80 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d nterrupted and m
18e90 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f ight continue to
18ea0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a completion..**.
18eb0 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 ** ^An SQL opera
18ec0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 tion that is int
18ed0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 errupted will re
18ee0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 turn [SQLITE_INT
18ef0 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 ERRUPT]..** ^If
18f00 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 the interrupted
18f10 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 SQL operation is
18f20 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 an INSERT, UPDA
18f30 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a TE, or DELETE.**
18f40 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 that is inside
18f50 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e an explicit tran
18f60 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 saction, then th
18f70 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 e entire transac
18f80 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 tion.** will be
18f90 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f rolled back auto
18fa0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a matically..**.**
18fb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
18fc0 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 terrupt(D) call
18fd0 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 is in effect unt
18fe0 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 il all currently
18ff0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 running.** SQL
19000 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 statements on [d
19010 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19020 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 on] D complete.
19030 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 ^Any new SQL st
19040 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
19050 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
19060 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 er the sqlite3_i
19070 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 nterrupt() call
19080 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a and before the .
19090 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 ** running state
190a0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 ments reaches ze
190b0 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 ro are interrupt
190c0 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 ed as if they ha
190d0 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e d been.** runnin
190e0 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 g prior to the s
190f0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
19100 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 () call. ^New S
19110 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
19120 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 that are starte
19130 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e d after the runn
19140 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f ing statement co
19150 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f unt reaches zero
19160 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 are.** not effe
19170 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 cted by the sqli
19180 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e te3_interrupt().
19190 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 .** ^A call to s
191a0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
191b0 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 (D) that occurs
191c0 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e when there are n
191d0 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c o running.** SQL
191e0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 statements is a
191f0 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e no-op and has n
19200 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 o effect on SQL
19210 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
19220 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 at are started a
19230 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 fter the sqlite3
19240 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
19250 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a l returns..**.**
19260 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 If the database
19270 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 connection clos
19280 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 es while [sqlite
19290 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 3_interrupt()].*
192a0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 * is running the
192b0 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c n bad things wil
192c0 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e l likely happen.
192d0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
192e0 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 _interrupt(sqlit
192f0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
19300 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 I3REF: Determine
19310 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 If An SQL State
19320 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 ment Is Complete
19330 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
19340 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c tines are useful
19350 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d during command-
19360 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 line input to de
19370 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a termine if the.*
19380 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 * currently ente
19390 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 red text seems t
193a0 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 o form a complet
193b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
193c0 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f or.** if additio
193d0 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 nal input is nee
193e0 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 ded before sendi
193f0 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f ng the text into
19400 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 .** SQLite for p
19410 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 arsing. ^These
19420 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
19430 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 1 if the input s
19440 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 tring.** appears
19450 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 to be a complet
19460 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e e SQL statement.
19470 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 ^A statement i
19480 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a s judged to be.*
19490 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 * complete if it
194a0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d ends with a sem
194b0 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 icolon token and
194c0 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 is not a prefix
194d0 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f of a.** well-fo
194e0 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 rmed CREATE TRIG
194f0 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 GER statement.
19500 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 ^Semicolons that
19510 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 are embedded wi
19520 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c thin.** string l
19530 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 iterals or quote
19540 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d d identifier nam
19550 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 es or comments a
19560 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 re not.** indepe
19570 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 ndent tokens (th
19580 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 ey are part of t
19590 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 he token in whic
195a0 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d h they are.** em
195b0 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 bedded) and thus
195c0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 do not count as
195d0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 a statement ter
195e0 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 minator. ^White
195f0 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d space.** and com
19600 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f ments that follo
19610 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 w the final semi
19620 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 colon are ignore
19630 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 d..**.** ^These
19640 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
19650 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 0 if the stateme
19660 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 nt is incomplete
19670 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f . ^If a.** memo
19680 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
19690 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 ils, then SQLITE
196a0 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e _NOMEM is return
196b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 ed..**.** ^These
196c0 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 routines do not
196d0 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 parse the SQL s
196e0 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a tatements thus.*
196f0 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 * will not detec
19700 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 t syntactically
19710 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a incorrect SQL..*
19720 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 *.** ^(If SQLite
19730 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e has not been in
19740 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 itialized using
19750 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
19760 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a ize()] prior .**
19770 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c to invoking sql
19780 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
19790 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 ) then sqlite3_i
197a0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
197b0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 nvoked.** automa
197c0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 tically by sqlit
197d0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e e3_complete16().
197e0 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 If that initia
197f0 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a lization fails,.
19800 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 ** then the retu
19810 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 rn value from sq
19820 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
19830 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a () will be non-z
19840 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 ero.** regardles
19850 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
19860 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 not the input SQ
19870 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e L is complete.)^
19880 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 .**.** The input
19890 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d to [sqlite3_com
198a0 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 plete()] must be
198b0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
198c0 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 ed.** UTF-8 stri
198d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e ng..**.** The in
198e0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
198f0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 complete16()] mu
19900 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 st be a zero-ter
19910 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 minated.** UTF-1
19920 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 6 string in nati
19930 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
19940 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f /.int sqlite3_co
19950 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 mplete(const cha
19960 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c r *sql);.int sql
19970 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
19980 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 const void *sql)
19990 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
199a0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 F: Register A Ca
199b0 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 llback To Handle
199c0 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 SQLITE_BUSY Err
199d0 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ors.** KEYWORDS:
199e0 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 {busy-handler c
199f0 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 allback} {busy h
19a00 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f andler}.** METHO
19a10 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
19a20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 ^The sqlite3_bu
19a30 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 sy_handler(D,X,P
19a40 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 ) routine sets a
19a50 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
19a60 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 on X.** that mig
19a70 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 ht be invoked wi
19a80 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 th argument P wh
19a90 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 enever.** an att
19aa0 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 empt is made to
19ab0 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73 access a databas
19ac0 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 e table associat
19ad0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 ed with.** [data
19ae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
19af0 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 D when another
19b00 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f thread.** or pro
19b10 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62 cess has the tab
19b20 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 le locked..** Th
19b30 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 e sqlite3_busy_h
19b40 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 andler() interfa
19b50 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d ce is used to im
19b60 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 plement.** [sqli
19b70 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
19b80 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 ()] and [PRAGMA
19b90 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a busy_timeout]..*
19ba0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 *.** ^If the bus
19bb0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
19bc0 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 LL, then [SQLITE
19bd0 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 _BUSY].** is ret
19be0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
19bf0 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 y upon encounter
19c00 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e ing the lock. ^
19c10 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c If the busy call
19c20 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e back.** is not N
19c30 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 ULL, then the ca
19c40 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 llback might be
19c50 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f invoked with two
19c60 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a arguments..**.*
19c70 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
19c80 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 ument to the bus
19c90 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 y handler is a c
19ca0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a opy of the void*
19cb0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a pointer which.*
19cc0 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 * is the third a
19cd0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
19ce0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
19cf0 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 ). ^The second
19d00 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 argument to.** t
19d10 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
19d20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
19d30 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 number of times
19d40 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 that the busy ha
19d50 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 ndler has.** bee
19d60 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f n invoked previo
19d70 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d usly for the sam
19d80 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e e locking event.
19d90 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 ^If the.** bus
19da0 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 y callback retur
19db0 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 ns 0, then no ad
19dc0 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 ditional attempt
19dd0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a s are made to.**
19de0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 access the data
19df0 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 base and [SQLITE
19e00 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e _BUSY] is return
19e10 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 ed.** to the app
19e20 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 lication..** ^If
19e30 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
19e40 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
19e50 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 then another att
19e60 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 empt.** is made
19e70 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 to access the da
19e80 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 tabase and the c
19e90 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a ycle repeats..**
19ea0 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 .** The presence
19eb0 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c of a busy handl
19ec0 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 er does not guar
19ed0 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 antee that it wi
19ee0 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a ll be invoked.**
19ef0 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c when there is l
19f00 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 ock contention.
19f10 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 ^If SQLite deter
19f20 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b mines that invok
19f30 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 ing the busy.**
19f40 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 handler could re
19f50 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f sult in a deadlo
19f60 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 ck, it will go a
19f70 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 head and return
19f80 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a [SQLITE_BUSY].**
19f90 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 to the applicat
19fa0 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 ion instead of i
19fb0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 nvoking the .**
19fc0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a busy handler..**
19fd0 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e Consider a scen
19fe0 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 ario where one p
19ff0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
1a000 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 g a read lock th
1a010 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 at.** it is tryi
1a020 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f ng to promote to
1a030 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b a reserved lock
1a040 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 and.** a second
1a050 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 process is hold
1a060 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c ing a reserved l
1a070 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 ock that it is t
1a080 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d rying.** to prom
1a090 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 ote to an exclus
1a0a0 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 ive lock. The f
1a0b0 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e irst process can
1a0c0 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 not proceed.** b
1a0d0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f ecause it is blo
1a0e0 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f cked by the seco
1a0f0 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e nd and the secon
1a100 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 d process cannot
1a110 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 .** proceed beca
1a120 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 use it is blocke
1a130 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 d by the first.
1a140 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 If both process
1a150 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 es.** invoke the
1a160 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 busy handlers,
1a170 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b neither will mak
1a180 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 e any progress.
1a190 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 Therefore,.** S
1a1a0 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 QLite returns [S
1a1b0 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 QLITE_BUSY] for
1a1c0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 the first proces
1a1d0 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 s, hoping that t
1a1e0 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 his.** will indu
1a1f0 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f ce the first pro
1a200 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 cess to release
1a210 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e its read lock an
1a220 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 d allow.** the s
1a230 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f econd process to
1a240 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 proceed..**.**
1a250 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 ^The default bus
1a260 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
1a270 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 LL..**.** ^(Ther
1a280 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
1a290 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
1a2a0 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 ler defined for
1a2b0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 each.** [databas
1a2c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
1a2d0 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 Setting a new bu
1a2e0 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 sy handler clear
1a2f0 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 s any.** previou
1a300 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e sly set handler.
1a310 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 )^ ^Note that c
1a320 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
1a330 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a busy_timeout()].
1a340 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 ** or evaluating
1a350 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 [PRAGMA busy_ti
1a360 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 meout=N] will ch
1a370 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 ange the.** busy
1a380 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 handler and thu
1a390 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 s clear any prev
1a3a0 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 iously set busy
1a3b0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 handler..**.** T
1a3c0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
1a3d0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 should not take
1a3e0 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 any actions whi
1a3f0 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a ch modify the.**
1a400 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1a410 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
1a420 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c d the busy handl
1a430 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f er. In other wo
1a440 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 rds,.** the busy
1a450 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 handler is not
1a460 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 reentrant. Any
1a470 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 such actions.**
1a480 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 result in undefi
1a490 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
1a4a0 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 .** A busy hand
1a4b0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f ler must not clo
1a4c0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
1a4d0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 connection.** or
1a4e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1a4f0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b ment] that invok
1a500 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ed the busy hand
1a510 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ler..*/.int sqli
1a520 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
1a530 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a (sqlite3*, int(*
1a540 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f )(void*,int), vo
1a550 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
1a560 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 I3REF: Set A Bus
1a570 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 y Timeout.** MET
1a580 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
1a590 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
1a5a0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 sets a [sqlite3
1a5b0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 _busy_handler |
1a5c0 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 busy handler] th
1a5d0 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 at sleeps.** for
1a5e0 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f a specified amo
1a5f0 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e unt of time when
1a600 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b a table is lock
1a610 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 ed. ^The handle
1a620 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 r.** will sleep
1a630 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 multiple times u
1a640 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d ntil at least "m
1a650 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
1a660 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 of sleeping.** h
1a670 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e ave accumulated.
1a680 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 ^After at leas
1a690 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f t "ms" milliseco
1a6a0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c nds of sleeping,
1a6b0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 .** the handler
1a6c0 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 returns 0 which
1a6d0 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f causes [sqlite3_
1a6e0 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 step()] to retur
1a6f0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 n.** [SQLITE_BUS
1a700 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 Y]..**.** ^Calli
1a710 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ng this routine
1a720 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 with an argument
1a730 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 less than or eq
1a740 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 ual to zero.** t
1a750 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 urns off all bus
1a760 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a y handlers..**.*
1a770 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e * ^(There can on
1a780 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 ly be a single b
1a790 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 usy handler for
1a7a0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 a particular.**
1a7b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1a7c0 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 tion] at any giv
1a7d0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 en moment. If a
1a7e0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 nother busy hand
1a7f0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e ler.** was defin
1a800 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 ed (using [sqli
1a810 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
1a820 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 ()]) prior to ca
1a830 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f lling.** this ro
1a840 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 utine, that othe
1a850 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 r busy handler i
1a860 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a s cleared.)^.**.
1a870 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 ** See also: [P
1a880 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f RAGMA busy_timeo
1a890 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ut].*/.int sqlit
1a8a0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
1a8b0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 sqlite3*, int ms
1a8c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1a8d0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 EF: Convenience
1a8e0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e Routines For Run
1a8f0 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 ning Queries.**
1a900 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
1a910 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 **.** This is a
1a920 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
1a930 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 that is preserv
1a940 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
1a950 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a compatibility..
1a960 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 ** Use of this i
1a970 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
1a980 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a recommended..**.
1a990 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 ** Definition: A
1a9a0 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 <b>result table
1a9b0 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 </b> is memory d
1a9c0 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 ata structure cr
1a9d0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 eated by the.**
1a9e0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
1a9f0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e le()] interface.
1aa00 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 A result table
1aa10 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 records the.**
1aa20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 complete query r
1aa30 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 esults from one
1aa40 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e or more queries.
1aa50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 .**.** The table
1aa60 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 conceptually ha
1aa70 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f s a number of ro
1aa80 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 ws and columns.
1aa90 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 But.** these nu
1aaa0 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 mbers are not pa
1aab0 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 rt of the result
1aac0 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 table itself.
1aad0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 These.** numbers
1aae0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 are obtained se
1aaf0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e parately. Let N
1ab00 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
1ab10 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 f rows.** and M
1ab20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 be the number of
1ab30 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 columns..**.**
1ab40 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 A result table i
1ab50 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
1ab60 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 inters to zero-t
1ab70 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
1ab80 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 strings..** Ther
1ab90 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c e are (N+1)*M el
1aba0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 ements in the ar
1abb0 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 ray. The first
1abc0 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 M pointers point
1abd0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d .** to zero-term
1abe0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 inated strings t
1abf0 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 hat contain the
1ac00 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f names of the co
1ac10 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 lumns..** The re
1ac20 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 maining entries
1ac30 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 all point to que
1ac40 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c ry results. NUL
1ac50 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a L values result.
1ac60 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 ** in NULL point
1ac70 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 ers. All other
1ac80 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 values are in th
1ac90 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 eir UTF-8 zero-t
1aca0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 erminated.** str
1acb0 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 ing representati
1acc0 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 on as returned b
1acd0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
1ace0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a n_text()]..**.**
1acf0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
1ad00 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 might consist of
1ad10 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d one or more mem
1ad20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e ory allocations.
1ad30 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
1ad40 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 fe to pass a res
1ad50 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 ult table direct
1ad60 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ly to [sqlite3_f
1ad70 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 ree()]..** A res
1ad80 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 ult table should
1ad90 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
1ada0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
1adb0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a ree_table()]..**
1adc0 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d .** ^(As an exam
1add0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ple of the resul
1ade0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 t table format,
1adf0 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 suppose a query
1ae00 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 result.** is as
1ae10 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
1ae20 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1ae30 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 .** Name
1ae40 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 | Age.**
1ae50 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------
1ae60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a --------------.*
1ae70 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 * Alice
1ae80 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 | 43.**
1ae90 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 Bob
1aea0 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 | 28.** C
1aeb0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a indy | 21.
1aec0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1aed0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
1aee0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d re are two colum
1aef0 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 n (M==2) and thr
1af00 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 ee rows (N==3).
1af10 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 Thus the.** res
1af20 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 ult table has 8
1af30 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 entries. Suppos
1af40 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 e the result tab
1af50 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 le is stored.**
1af60 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 in an array name
1af70 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 s azResult. The
1af80 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 n azResult holds
1af90 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a this content:.*
1afa0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1afb0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 ><pre>.**
1afc0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d azResult[0]
1afd0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 = "Name";.**
1afe0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1aff0 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 1;1] = "Age";.**
1b000 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1b010 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 [2] = "Alice
1b020 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1b030 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 esult[3] = "
1b040 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 43";.** a
1b050 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d zResult[4] =
1b060 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 "Bob";.**
1b070 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 azResult[5
1b080 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 ] = "28";.**
1b090 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1b0a0 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a ;6] = "Cindy";.*
1b0b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1b0c0 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b t[7] = "21";
1b0d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1b0e0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 kquote>)^.**.**
1b0f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 ^The sqlite3_get
1b100 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f _table() functio
1b110 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 n evaluates one
1b120 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 or more.** semic
1b130 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 olon-separated S
1b140 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e QL statements in
1b150 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
1b160 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 ated UTF-8.** st
1b170 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 ring of its 2nd
1b180 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 parameter and re
1b190 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 turns a result t
1b1a0 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 able to the.** p
1b1b0 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 ointer given in
1b1c0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 its 3rd paramete
1b1d0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 r..**.** After t
1b1e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 he application h
1b1f0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
1b200 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
1b210 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1b220 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 le(),.** it must
1b230 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 pass the result
1b240 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 table pointer t
1b250 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 o sqlite3_free_t
1b260 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 able() in order
1b270 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 to.** release th
1b280 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 e memory that wa
1b290 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 s malloced. Bec
1b2a0 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 ause of the way
1b2b0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1b2c0 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e malloc()] happen
1b2d0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 s within sqlite3
1b2e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 _get_table(), th
1b2f0 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e e calling.** fun
1b300 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 ction must not t
1b310 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 ry to call [sqli
1b320 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 te3_free()] dire
1b330 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b ctly. Only.** [
1b340 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
1b350 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f le()] is able to
1b360 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d release the mem
1b370 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 ory properly and
1b380 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 safely..**.** T
1b390 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
1b3a0 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 able() interface
1b3b0 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 is implemented
1b3c0 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f as a wrapper aro
1b3d0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f und.** [sqlite3_
1b3e0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 exec()]. The sq
1b3f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1b400 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e ) routine does n
1b410 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a ot have access.*
1b420 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 * to any interna
1b430 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 l data structure
1b440 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 s of SQLite. It
1b450 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 uses only the p
1b460 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 ublic.** interfa
1b470 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e ce defined here.
1b480 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e As a consequen
1b490 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 ce, errors that
1b4a0 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 occur in the.**
1b4b0 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 wrapper layer ou
1b4c0 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 tside of the int
1b4d0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 ernal [sqlite3_e
1b4e0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 xec()] call are
1b4f0 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 not.** reflected
1b500 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 in subsequent c
1b510 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
1b520 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a _errcode()] or.*
1b530 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 * [sqlite3_errms
1b540 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c g()]..*/.int sql
1b550 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a ite3_get_table(.
1b560 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
1b570 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 /* An op
1b580 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 en database */.
1b590 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
1b5a0 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f l, /* SQL to
1b5b0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
1b5c0 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 . char ***pazRe
1b5d0 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 sult, /* Resu
1b5e0 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 lts of the query
1b5f0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 */. int *pnRow
1b600 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e , /* N
1b610 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
1b620 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 rows written her
1b630 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f e */. int *pnCo
1b640 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 lumn, /*
1b650 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 Number of result
1b660 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e columns written
1b670 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 here */. char
1b680 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 **pzErrmsg
1b690 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 /* Error msg wr
1b6a0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b itten here */.);
1b6b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 .void sqlite3_fr
1b6c0 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a ee_table(char **
1b6d0 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 result);../*.**
1b6e0 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 CAPI3REF: Format
1b6f0 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 ted String Print
1b700 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a ing Functions.**
1b710 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
1b720 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b es are work-alik
1b730 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 es of the "print
1b740 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 f()" family of f
1b750 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d unctions.** from
1b760 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
1b770 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 library..** Thes
1b780 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 e routines under
1b790 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 stand most of th
1b7a0 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 e common K&R for
1b7b0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c matting options,
1b7c0 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 .** plus some ad
1b7d0 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 ditional non-sta
1b7e0 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 ndard formats, d
1b7f0 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a etailed below..*
1b800 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 * Note that some
1b810 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 of the more obs
1b820 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 cure formatting
1b830 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 options from rec
1b840 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 ent.** C-library
1b850 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f standards are o
1b860 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 mitted from this
1b870 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
1b880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1b890 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e te3_mprintf() an
1b8a0 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e d sqlite3_vmprin
1b8b0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 tf() routines wr
1b8c0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 ite their.** res
1b8d0 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 ults into memory
1b8e0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
1b8f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1b900 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 ]..** The string
1b910 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
1b920 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 ese two routines
1b930 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 should be.** re
1b940 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 leased by [sqlit
1b950 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f e3_free()]. ^Bo
1b960 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 th routines retu
1b970 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 rn a.** NULL poi
1b980 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 nter if [sqlite3
1b990 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e _malloc()] is un
1b9a0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
1b9b0 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 enough.** memor
1b9c0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 y to hold the re
1b9d0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a sulting string..
1b9e0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 **.** ^(The sqli
1b9f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 te3_snprintf() r
1ba00 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 outine is simila
1ba10 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 r to "snprintf()
1ba20 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 " from.** the st
1ba30 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
1ba40 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 . The result is
1ba50 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
1ba60 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 e.** buffer supp
1ba70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f lied as the seco
1ba80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f nd parameter who
1ba90 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e se size is given
1baa0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 by.** the first
1bab0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 parameter. Note
1bac0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 that the order
1bad0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 of the.** first
1bae0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 two parameters i
1baf0 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 s reversed from
1bb00 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 snprintf().)^ T
1bb10 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 his is an.** his
1bb20 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 torical accident
1bb30 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 that cannot be
1bb40 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 fixed without br
1bb50 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 eaking.** backwa
1bb60 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
1bb70 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 y. ^(Note also
1bb80 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 that sqlite3_snp
1bb90 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 rintf().** retur
1bba0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
1bbb0 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 its buffer inste
1bbc0 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 ad of the number
1bbd0 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 of.** character
1bbe0 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 s actually writt
1bbf0 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 en into the buff
1bc00 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 er.)^ We admit
1bc10 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 that.** the numb
1bc20 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
1bc30 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 written would b
1bc40 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 e a more useful
1bc50 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 return.** value
1bc60 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 but we cannot ch
1bc70 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 ange the impleme
1bc80 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 ntation of sqlit
1bc90 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
1bca0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 now without bre
1bcb0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c aking compatibil
1bcc0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c ity..**.** ^As l
1bcd0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 ong as the buffe
1bce0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 r size is greate
1bcf0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c r than zero, sql
1bd00 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
1bd10 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 ** guarantees th
1bd20 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 at the buffer is
1bd30 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 always zero-ter
1bd40 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 minated. ^The f
1bd50 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 irst.** paramete
1bd60 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 r "n" is the tot
1bd70 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 al size of the b
1bd80 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 uffer, including
1bd90 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 space for.** th
1bda0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
1bdb0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 r. So the longe
1bdc0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 st string that c
1bdd0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 an be completely
1bde0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c .** written will
1bdf0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 be n-1 characte
1be00 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 rs..**.** ^The s
1be10 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 qlite3_vsnprintf
1be20 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 () routine is a
1be30 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 varargs version
1be40 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 of sqlite3_snpri
1be50 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ntf()..**.** The
1be60 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 se routines all
1be70 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 implement some a
1be80 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 dditional format
1be90 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 ting.** options
1bea0 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 that are useful
1beb0 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 for constructing
1bec0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e SQL statements.
1bed0 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 .** All of the u
1bee0 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f sual printf() fo
1bef0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 rmatting options
1bf00 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 apply. In addi
1bf10 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 tion, there.** i
1bf20 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 s are "%q", "%Q"
1bf30 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 , "%w" and "%z"
1bf40 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e options..**.** ^
1bf50 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 (The %q option w
1bf60 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 orks like %s in
1bf70 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 that it substitu
1bf80 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e tes a nul-termin
1bf90 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 ated.** string f
1bfa0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 rom the argument
1bfb0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 list. But %q a
1bfc0 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 lso doubles ever
1bfd0 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 y '\'' character
1bfe0 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 ..** %q is desig
1bff0 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 ned for use insi
1c000 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 de a string lite
1c010 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c ral.)^ By doubl
1c020 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a ing each '\''.**
1c030 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 character it es
1c040 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 capes that chara
1c050 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 cter and allows
1c060 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 it to be inserte
1c070 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 d into.** the st
1c080 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 ring..**.** For
1c090 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 example, assume
1c0a0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 the string varia
1c0b0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 ble zText contai
1c0c0 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f ns text as follo
1c0d0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
1c0e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1c0f0 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 char *zText = "I
1c100 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 t's a happy day!
1c110 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c ";.** </pre></bl
1c120 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
1c130 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 One can use this
1c140 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 text in an SQL
1c150 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c statement as fol
1c160 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
1c170 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1c180 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 char *zSQL = s
1c190 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 qlite3_mprintf("
1c1a0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
1c1b0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c e VALUES('%q')",
1c1c0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c zText);.** sql
1c1d0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 ite3_exec(db, zS
1c1e0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a QL, 0, 0, 0);.**
1c1f0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a sqlite3_free(z
1c200 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c SQL);.** </pre><
1c210 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
1c220 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 ** Because the %
1c230 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 q format string
1c240 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 is used, the '\'
1c250 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a ' character in z
1c260 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 Text.** is escap
1c270 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 ed and the SQL g
1c280 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 enerated is as f
1c290 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
1c2a0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1c2b0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 ** INSERT INTO
1c2c0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 table1 VALUES('I
1c2d0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 t''s a happy day
1c2e0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 !').** </pre></b
1c2f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1c300 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 This is correct
1c310 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 . Had we used %
1c320 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c s instead of %q,
1c330 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 the generated S
1c340 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 QL.** would have
1c350 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 looked like thi
1c360 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
1c370 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 uote><pre>.** I
1c380 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
1c390 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 1 VALUES('It's a
1c3a0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a happy day!');.*
1c3b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1c3c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 uote>.**.** This
1c3d0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 second example
1c3e0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 is an SQL syntax
1c3f0 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 error. As a ge
1c400 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 neral rule you s
1c410 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 hould.** always
1c420 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f use %q instead o
1c430 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 f %s when insert
1c440 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 ing text into a
1c450 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a string literal..
1c460 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f **.** ^(The %Q o
1c470 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
1c480 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c %q except it al
1c490 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 so adds single q
1c4a0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 uotes around.**
1c4b0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 the outside of t
1c4c0 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e he total string.
1c4d0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 Additionally,
1c4e0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
1c4f0 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d in the.** argum
1c500 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 ent list is a NU
1c510 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 LL pointer, %Q s
1c520 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 ubstitutes the t
1c530 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 ext "NULL" (with
1c540 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 out.** single qu
1c550 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f otes).)^ So, fo
1c560 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 r example, one c
1c570 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 ould say:.**.**
1c580 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1c590 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c >.** char *zSQL
1c5a0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e = sqlite3_mprin
1c5b0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 tf("INSERT INTO
1c5c0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 table VALUES(%Q)
1c5d0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 ", zText);.** s
1c5e0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 qlite3_exec(db,
1c5f0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a zSQL, 0, 0, 0);.
1c600 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ** sqlite3_free
1c610 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 (zSQL);.** </pre
1c620 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1c630 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 *.** The code ab
1c640 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 ove will render
1c650 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 a correct SQL st
1c660 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a atement in the z
1c670 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 SQL.** variable
1c680 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 even if the zTex
1c690 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 t variable is a
1c6a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
1c6b0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 .** ^(The "%w" f
1c6c0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
1c6d0 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 is like "%q" ex
1c6e0 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70 cept that it exp
1c6f0 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f ects to.** be co
1c700 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 ntained within d
1c710 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 ouble-quotes ins
1c720 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 tead of single q
1c730 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a uotes, and it.**
1c740 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 escapes the dou
1c750 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 ble-quote charac
1c760 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 ter instead of t
1c770 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a he single-quote.
1c780 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 ** character.)^
1c790 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 The "%w" format
1c7a0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 ting option is i
1c7b0 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 ntended for safe
1c7c0 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 ly inserting.**
1c7d0 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e table and column
1c7e0 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f names into a co
1c7f0 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 nstructed SQL st
1c800 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e atement..**.** ^
1c810 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 (The "%z" format
1c820 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b ting option work
1c830 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 s like "%s" but
1c840 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 with the.** addi
1c850 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 tion that after
1c860 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 the string has b
1c870 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 een read and cop
1c880 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 ied into.** the
1c890 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 result, [sqlite3
1c8a0 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c _free()] is call
1c8b0 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 ed on the input
1c8c0 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 string.)^.*/.cha
1c8d0 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e r *sqlite3_mprin
1c8e0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e tf(const char*,.
1c8f0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 ..);.char *sqlit
1c900 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 e3_vmprintf(cons
1c910 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 t char*, va_list
1c920 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
1c930 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 _snprintf(int,ch
1c940 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
1c950 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c ...);.char *sql
1c960 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 ite3_vsnprintf(i
1c970 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 nt,char*,const c
1c980 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a har*, va_list);.
1c990 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1c9a0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 Memory Allocati
1c9b0 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a on Subsystem.**.
1c9c0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f ** The SQLite co
1c9d0 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 re uses these th
1c9e0 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 ree routines for
1c9f0 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a all of its own.
1ca00 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f ** internal memo
1ca10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
1ca20 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 eds. "Core" in t
1ca30 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 he previous sent
1ca40 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 ence.** does not
1ca50 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 include operati
1ca60 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 ng-system specif
1ca70 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 ic VFS implement
1ca80 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 ation. The.** W
1ca90 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 indows VFS uses
1caa0 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 native malloc()
1cab0 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 and free() for s
1cac0 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a ome operations..
1cad0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1cae0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 e3_malloc() rout
1caf0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ine returns a po
1cb00 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b inter to a block
1cb10 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 .** of memory at
1cb20 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 least N bytes i
1cb30 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 n length, where
1cb40 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 N is the paramet
1cb50 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 er..** ^If sqlit
1cb60 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 e3_malloc() is u
1cb70 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 nable to obtain
1cb80 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a sufficient free.
1cb90 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 ** memory, it re
1cba0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
1cbb0 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 nter. ^If the p
1cbc0 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a arameter N to.**
1cbd0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1cbe0 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 ) is zero or neg
1cbf0 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 ative then sqlit
1cc00 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 e3_malloc() retu
1cc10 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f rns.** a NULL po
1cc20 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
1cc30 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 e sqlite3_malloc
1cc40 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 64(N) routine wo
1cc50 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a rks just like.**
1cc60 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1cc70 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e N) except that N
1cc80 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 is an unsigned
1cc90 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 64-bit integer i
1cca0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 nstead.** of a s
1ccb0 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 igned 32-bit int
1ccc0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c eger..**.** ^Cal
1ccd0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 ling sqlite3_fre
1cce0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 e() with a point
1ccf0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 er previously re
1cd00 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c turned.** by sql
1cd10 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 ite3_malloc() or
1cd20 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1cd30 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 () releases that
1cd40 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 memory so.** th
1cd50 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 at it might be r
1cd60 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c eused. ^The sql
1cd70 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 ite3_free() rout
1cd80 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f ine is.** a no-o
1cd90 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 p if is called w
1cda0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
1cdb0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e er. Passing a N
1cdc0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 ULL pointer.** t
1cdd0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 o sqlite3_free()
1cde0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 is harmless. A
1cdf0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 fter being freed
1ce00 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 , memory.** shou
1ce10 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 ld neither be re
1ce20 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 ad nor written.
1ce30 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 Even reading pr
1ce40 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a eviously freed.*
1ce50 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 * memory might r
1ce60 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 esult in a segme
1ce70 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 ntation fault or
1ce80 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
1ce90 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 ror..** Memory c
1cea0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 orruption, a seg
1ceb0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c mentation fault,
1cec0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 or other severe
1ced0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 error.** might
1cee0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 result if sqlite
1cef0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 3_free() is call
1cf00 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 ed with a non-NU
1cf10 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a LL pointer that.
1cf20 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 ** was not obtai
1cf30 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
1cf40 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c _malloc() or sql
1cf50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
1cf60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1cf70 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 e3_realloc(X,N)
1cf80 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
1cf90 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a ts to resize a.*
1cfa0 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 * prior memory a
1cfb0 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 llocation X to b
1cfc0 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 e at least N byt
1cfd0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 es..** ^If the X
1cfe0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
1cff0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
1d000 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 N).** is a NULL
1d010 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 pointer then its
1d020 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 behavior is ide
1d030 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e ntical to callin
1d040 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c g.** sqlite3_mal
1d050 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 loc(N)..** ^If t
1d060 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 he N parameter t
1d070 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
1d080 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f c(X,N) is zero o
1d090 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 r.** negative th
1d0a0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
1d0b0 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 is exactly the s
1d0c0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a ame as calling.*
1d0d0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 * sqlite3_free(X
1d0e0 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 )..** ^sqlite3_r
1d0f0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 ealloc(X,N) retu
1d100 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1d110 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
1d120 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 tion.** of at le
1d130 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 ast N bytes in s
1d140 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 ize or NULL if i
1d150 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f nsufficient memo
1d160 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e ry is available.
1d170 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 .** ^If M is the
1d180 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 size of the pri
1d190 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 or allocation, t
1d1a0 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 hen min(N,M) byt
1d1b0 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 es.** of the pri
1d1c0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 or allocation ar
1d1d0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 e copied into th
1d1e0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 e beginning of b
1d1f0 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a uffer returned.*
1d200 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 * by sqlite3_rea
1d210 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 lloc(X,N) and th
1d220 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
1d230 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 on is freed..**
1d240 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c ^If sqlite3_real
1d250 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 loc(X,N) returns
1d260 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 NULL and N is p
1d270 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 ositive, then th
1d280 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 e.** prior alloc
1d290 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 ation is not fre
1d2a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
1d2b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 qlite3_realloc64
1d2c0 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 (X,N) interfaces
1d2d0 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 works the same
1d2e0 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 as.** sqlite3_re
1d2f0 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 alloc(X,N) excep
1d300 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 t that N is a 64
1d310 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e -bit unsigned in
1d320 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a teger instead.**
1d330 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 of a 32-bit sig
1d340 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a ned integer..**.
1d350 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 ** ^If X is a me
1d360 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
1d370 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
1d380 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
1d390 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 _malloc(),.** sq
1d3a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 lite3_malloc64()
1d3b0 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f , sqlite3_reallo
1d3c0 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f c(), or sqlite3_
1d3d0 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 realloc64(), the
1d3e0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 n.** sqlite3_msi
1d3f0 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 ze(X) returns th
1d400 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d e size of that m
1d410 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1d420 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 in bytes..** ^T
1d430 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
1d440 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 d by sqlite3_msi
1d450 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c ze(X) might be l
1d460 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e arger than the n
1d470 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 umber.** of byte
1d480 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e s requested when
1d490 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 X was allocated
1d4a0 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 . ^If X is a NU
1d4b0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a LL pointer then.
1d4c0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 ** sqlite3_msize
1d4d0 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f (X) returns zero
1d4e0 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 . If X points t
1d4f0 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 o something that
1d500 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 is not.** the b
1d510 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f eginning of memo
1d520 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f ry allocation, o
1d530 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 r if it points t
1d540 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 o a formerly.**
1d550 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c valid memory all
1d560 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 ocation that has
1d570 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c now been freed,
1d580 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
1d590 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 or.** of sqlite3
1d5a0 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 _msize(X) is und
1d5b0 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 efined and possi
1d5c0 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a bly harmful..**.
1d5d0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 ** ^The memory r
1d5e0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
1d5f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c e3_malloc(), sql
1d600 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a ite3_realloc(),.
1d610 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
1d620 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 c64(), and sqlit
1d630 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a e3_realloc64().*
1d640 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 * is always alig
1d650 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 ned to at least
1d660 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 an 8 byte bounda
1d670 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 ry, or to a.** 4
1d680 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 byte boundary i
1d690 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f f the [SQLITE_4_
1d6a0 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c BYTE_ALIGNED_MAL
1d6b0 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d LOC] compile-tim
1d6c0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 e.** option is u
1d6d0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 sed..**.** In SQ
1d6e0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
1d6f0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 .0 and 3.5.1, it
1d700 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f was possible to
1d710 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 define.** the S
1d720 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 QLITE_OMIT_MEMOR
1d730 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 Y_ALLOCATION whi
1d740 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 ch would cause t
1d750 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 he built-in.** i
1d760 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
1d770 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
1d780 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 to be omitted.
1d790 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a That capability.
1d7a0 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ** is no longer
1d7b0 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 provided. Only
1d7c0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
1d7d0 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 allocators can b
1d7e0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 e used..**.** Pr
1d7f0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 ior to SQLite ve
1d800 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 rsion 3.7.10, th
1d810 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 e Windows OS int
1d820 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c erface layer cal
1d830 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 led.** the syste
1d840 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 m malloc() and f
1d850 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 ree() directly w
1d860 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a hen converting.*
1d870 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 * filenames betw
1d880 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e een the UTF-8 en
1d890 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 coding used by S
1d8a0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 QLite.** and wha
1d8b0 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 tever filename e
1d8c0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 ncoding is used
1d8d0 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 by the particula
1d8e0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 r Windows.** ins
1d8f0 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f tallation. Memo
1d900 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
1d910 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 rors were detect
1d920 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 ed, but.** they
1d930 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 were reported ba
1d940 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 ck as [SQLITE_CA
1d950 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 NTOPEN] or.** [S
1d960 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 QLITE_IOERR] rat
1d970 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
1d980 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 _NOMEM]..**.** T
1d990 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d he pointer argum
1d9a0 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 ents to [sqlite3
1d9b0 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 _free()] and [sq
1d9c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
1d9d0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 .** must be eith
1d9e0 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 er NULL or else
1d9f0 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 pointers obtaine
1da00 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a d from a prior.*
1da10 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 * invocation of
1da20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1da30 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
1da40 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 ealloc()] that h
1da50 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 ave.** not yet b
1da60 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a een released..**
1da70 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
1da80 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 ion must not rea
1da90 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 d or write any p
1daa0 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 art of.** a bloc
1dab0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 k of memory afte
1dac0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 r it has been re
1dad0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 leased using.**
1dae0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1daf0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
1db00 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 lloc()]..*/.void
1db10 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 *sqlite3_malloc
1db20 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c (int);.void *sql
1db30 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 ite3_malloc64(sq
1db40 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 lite3_uint64);.v
1db50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 oid *sqlite3_rea
1db60 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 lloc(void*, int)
1db70 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f ;.void *sqlite3_
1db80 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c realloc64(void*,
1db90 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 sqlite3_uint64)
1dba0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 ;.void sqlite3_f
1dbb0 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 ree(void*);.sqli
1dbc0 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 te3_uint64 sqlit
1dbd0 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b e3_msize(void*);
1dbe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1dbf0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
1dc00 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a or Statistics.**
1dc10 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 .** SQLite provi
1dc20 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e des these two in
1dc30 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 terfaces for rep
1dc40 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 orting on the st
1dc50 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b atus.** of the [
1dc60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1dc70 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ], [sqlite3_free
1dc80 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
1dc90 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 3_realloc()].**
1dca0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 routines, which
1dcb0 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 form the built-i
1dcc0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
1dcd0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a ion subsystem..*
1dce0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 *.** ^The [sqlit
1dcf0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
1dd00 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
1dd10 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
1dd20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f bytes.** of memo
1dd30 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 ry currently out
1dd40 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 standing (malloc
1dd50 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 ed but not freed
1dd60 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 )..** ^The [sqli
1dd70 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
1dd80 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 ater()] routine
1dd90 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 returns the maxi
1dda0 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 mum.** value of
1ddb0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
1ddc0 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 used()] since th
1ddd0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 e high-water mar
1dde0 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 k.** was last re
1ddf0 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 set. ^The value
1de00 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
1de10 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
1de20 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 ed()] and.** [sq
1de30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
1de40 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 hwater()] includ
1de50 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a e any overhead.*
1de60 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 * added by SQLit
1de70 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 e in its impleme
1de80 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ntation of [sqli
1de90 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a te3_malloc()],.*
1dea0 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 * but not overhe
1deb0 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 ad added by the
1dec0 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 any underlying s
1ded0 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a ystem library.**
1dee0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b routines that [
1def0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1df00 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a ] may call..**.*
1df10 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 * ^The memory hi
1df20 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 gh-water mark is
1df30 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 reset to the cu
1df40 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a rrent value of.*
1df50 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 * [sqlite3_memor
1df60 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 y_used()] if and
1df70 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 only if the par
1df80 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 ameter to.** [sq
1df90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
1dfa0 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 hwater()] is tru
1dfb0 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 e. ^The value r
1dfc0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 eturned.** by [s
1dfd0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
1dfe0 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 ghwater(1)] is t
1dff0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
1e000 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 rk.** prior to t
1e010 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c he reset..*/.sql
1e020 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
1e030 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 e3_memory_used(v
1e040 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e oid);.sqlite3_in
1e050 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f t64 sqlite3_memo
1e060 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 ry_highwater(int
1e070 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a resetFlag);../*
1e080 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 .** CAPI3REF: Ps
1e090 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 eudo-Random Numb
1e0a0 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a er Generator.**.
1e0b0 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 ** SQLite contai
1e0c0 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 ns a high-qualit
1e0d0 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 y pseudo-random
1e0e0 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 number generator
1e0f0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a (PRNG) used to.
1e100 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d ** select random
1e110 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 [ROWID | ROWIDs
1e120 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 ] when inserting
1e130 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 new records int
1e140 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a o a table that.*
1e150 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 * already uses t
1e160 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 he largest possi
1e170 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 ble [ROWID]. Th
1e180 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 e PRNG is also u
1e190 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 sed for.** the b
1e1a0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 uild-in random()
1e1b0 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 and randomblob(
1e1c0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e ) SQL functions.
1e1d0 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 This interface
1e1e0 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 allows.** appli
1e1f0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 cations to acces
1e200 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 s the same PRNG
1e210 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 for other purpos
1e220 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c es..**.** ^A cal
1e230 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e l to this routin
1e240 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 e stores N bytes
1e250 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 of randomness i
1e260 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a nto buffer P..**
1e270 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 ^The P paramete
1e280 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 r can be a NULL
1e290 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
1e2a0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 If this routine
1e2b0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 has not been pre
1e2c0 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f viously called o
1e2d0 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 r if the previou
1e2e0 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 s.** call had N
1e2f0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 less than one or
1e300 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
1e310 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 for P, then the
1e320 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 PRNG is.** seede
1e330 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 d using randomne
1e340 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ss obtained from
1e350 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 the xRandomness
1e360 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 method of.** th
1e370 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
1e380 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a e3_vfs] object..
1e390 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 ** ^If the previ
1e3a0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 ous call to this
1e3b0 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 routine had an
1e3c0 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 N of 1 or more a
1e3d0 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c nd a.** non-NULL
1e3e0 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 P then the pseu
1e3f0 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 do-randomness is
1e400 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e generated.** in
1e410 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 ternally and wit
1e420 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f hout recourse to
1e430 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
1e440 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a s] xRandomness.*
1e450 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 * method..*/.voi
1e460 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d d sqlite3_random
1e470 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 ness(int N, void
1e480 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *P);../*.** CAP
1e490 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 I3REF: Compile-T
1e4a0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f ime Authorizatio
1e4b0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d n Callbacks.** M
1e4c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
1e4d0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
1e4e0 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 ne registers an
1e4f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1e500 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 ack with a parti
1e510 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 cular.** [databa
1e520 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 se connection],
1e530 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 supplied in the
1e540 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a first argument..
1e550 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a ** ^The authoriz
1e560 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
1e570 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 nvoked as SQL st
1e580 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 atements are bei
1e590 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 ng compiled.** b
1e5a0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 y [sqlite3_prepa
1e5b0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 re()] or its var
1e5c0 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 iants [sqlite3_p
1e5d0 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a repare_v2()],.**
1e5e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1e5f0 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 e16()] and [sqli
1e600 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
1e610 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 ()]. ^At variou
1e620 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 s.** points duri
1e630 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 ng the compilati
1e640 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c on process, as l
1e650 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 ogic is being cr
1e660 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 eated.** to perf
1e670 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 orm various acti
1e680 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 ons, the authori
1e690 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
1e6a0 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 invoked to.** se
1e6b0 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f e if those actio
1e6c0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 ns are allowed.
1e6d0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 ^The authorizer
1e6e0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 callback should
1e6f0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
1e700 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 TE_OK] to allow
1e710 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c the action, [SQL
1e720 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 ITE_IGNORE] to d
1e730 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 isallow the.** s
1e740 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 pecific action b
1e750 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c ut allow the SQL
1e760 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f statement to co
1e770 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 ntinue to be.**
1e780 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 compiled, or [SQ
1e790 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 LITE_DENY] to ca
1e7a0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 use the entire S
1e7b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 QL statement to
1e7c0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 be.** rejected w
1e7d0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e ith an error. ^
1e7e0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 If the authorize
1e7f0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 r callback retur
1e800 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 ns.** any value
1e810 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
1e820 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c TE_IGNORE], [SQL
1e830 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c ITE_OK], or [SQL
1e840 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 ITE_DENY].** the
1e850 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 n the [sqlite3_p
1e860 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
1e870 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 equivalent call
1e880 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a that triggered.*
1e890 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
1e8a0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 will fail with
1e8b0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
1e8c0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
1e8d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
1e8e0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 s [SQLITE_OK], t
1e8f0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 hat means the op
1e900 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 eration.** reque
1e910 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 sted is ok. ^Wh
1e920 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
1e930 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
1e940 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 DENY], the.** [s
1e950 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1e960 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 2()] or equivale
1e970 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 nt call that tri
1e980 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 ggered the.** au
1e990 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 thorizer will fa
1e9a0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 il with an error
1e9b0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e message explain
1e9c0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 ing that.** acce
1e9d0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a ss is denied. .*
1e9e0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
1e9f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
1ea00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1ea10 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f back is a copy o
1ea20 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 f the third.** p
1ea30 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
1ea40 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1ea50 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 orizer() interfa
1ea60 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 ce. ^The second
1ea70 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 parameter.** to
1ea80 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
1ea90 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 an integer [SQLI
1eaa0 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e TE_COPY | action
1eab0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 code] that spec
1eac0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 ifies.** the par
1ead0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 ticular action t
1eae0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e o be authorized.
1eaf0 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f ^The third thro
1eb00 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 ugh sixth parame
1eb10 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 ters.** to the c
1eb20 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f allback are zero
1eb30 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
1eb40 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e ngs that contain
1eb50 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 additional.** d
1eb60 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 etails about the
1eb70 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
1eb80 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 thorized..**.**
1eb90 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 ^If the action c
1eba0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 ode is [SQLITE_R
1ebb0 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 EAD].** and the
1ebc0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
1ebd0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
1ebe0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 then the.** [pr
1ebf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1ec00 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 ] statement is c
1ec10 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 onstructed to su
1ec20 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 bstitute.** a NU
1ec30 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 LL value in plac
1ec40 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 e of the table c
1ec50 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 olumn that would
1ec60 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 have.** been re
1ec70 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b ad if [SQLITE_OK
1ec80 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 ] had been retur
1ec90 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 ned. The [SQLIT
1eca0 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 E_IGNORE].** ret
1ecb0 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 urn can be used
1ecc0 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 to deny an untru
1ecd0 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 sted user access
1ece0 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a to individual.*
1ecf0 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 * columns of a t
1ed00 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 able..** ^If the
1ed10 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 action code is
1ed20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 [SQLITE_DELETE]
1ed30 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
1ed40 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c returns.** [SQL
1ed50 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e ITE_IGNORE] then
1ed60 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 the [DELETE] op
1ed70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 eration proceeds
1ed80 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 but the.** [tru
1ed90 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 ncate optimizati
1eda0 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 on] is disabled
1edb0 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 and all rows are
1edc0 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 deleted individ
1edd0 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 ually..**.** An
1ede0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 authorizer is us
1edf0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
1ee00 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
1ee10 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 ring].** SQL sta
1ee20 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 tements from an
1ee30 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
1ee40 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 , to ensure that
1ee50 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
1ee60 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 nts.** do not tr
1ee70 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 y to access data
1ee80 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c they are not al
1ee90 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 lowed to see, or
1eea0 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f that they do no
1eeb0 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 t.** try to exec
1eec0 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 ute malicious st
1eed0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 atements that da
1eee0 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 mage the databas
1eef0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 e. For.** examp
1ef00 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
1ef10 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 on may allow a u
1ef20 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 ser to enter arb
1ef30 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 itrary.** SQL qu
1ef40 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 eries for evalua
1ef50 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 tion by a databa
1ef60 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 se. But the app
1ef70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a lication does.**
1ef80 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 not want the us
1ef90 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f er to be able to
1efa0 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 make arbitrary
1efb0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a changes to the.*
1efc0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 * database. An
1efd0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 authorizer could
1efe0 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 then be put in
1eff0 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a place while the.
1f000 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 ** user-entered
1f010 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 SQL is being [sq
1f020 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
1f030 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a prepared] that.*
1f040 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 * disallows ever
1f050 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 ything except [S
1f060 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
1f070 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 s..**.** Applica
1f080 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 tions that need
1f090 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 to process SQL f
1f0a0 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f rom untrusted so
1f0b0 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 urces.** might a
1f0c0 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 lso consider low
1f0d0 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c ering resource l
1f0e0 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c imits using [sql
1f0f0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
1f100 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 and limiting da
1f110 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e tabase size usin
1f120 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f g the [max_page_
1f130 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a count] [PRAGMA].
1f140 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 ** in addition t
1f150 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f o using an autho
1f160 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f rizer..**.** ^(O
1f170 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 nly a single aut
1f180 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 horizer can be i
1f190 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 n place on a dat
1f1a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1f1b0 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 .** at a time.
1f1c0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c Each call to sql
1f1d0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
1f1e0 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 zer overrides th
1f1f0 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 e.** previous ca
1f200 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 ll.)^ ^Disable
1f210 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 the authorizer b
1f220 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e y installing a N
1f230 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ULL callback..**
1f240 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 The authorizer
1f250 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 is disabled by d
1f260 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 efault..**.** Th
1f270 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1f280 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 lback must not d
1f290 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
1f2a0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
1f2b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1f2c0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
1f2d0 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a ked the authoriz
1f2e0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 er callback..**
1f2f0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 Note that [sqlit
1f300 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1f310 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
1f320 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 ep()] both modif
1f330 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 y their.** datab
1f340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
1f350 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 for the meaning
1f360 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 of "modify" in t
1f370 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a his paragraph..*
1f380 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 *.** ^When [sqli
1f390 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1f3a0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 ] is used to pre
1f3b0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 pare a statement
1f3c0 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 , the.** stateme
1f3d0 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 nt might be re-p
1f3e0 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b repared during [
1f3f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1f400 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 due to a .** sch
1f410 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e ema change. Hen
1f420 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 ce, the applicat
1f430 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 ion should ensur
1f440 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f e that the.** co
1f450 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 rrect authorizer
1f460 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e callback remain
1f470 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e s in place durin
1f480 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 g the [sqlite3_s
1f490 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e tep()]..**.** ^N
1f4a0 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 ote that the aut
1f4b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1f4c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 is invoked only
1f4d0 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 during.** [sqli
1f4e0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
1f4f0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 r its variants.
1f500 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 Authorization i
1f510 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d s not.** perform
1f520 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d ed during statem
1f530 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 ent evaluation i
1f540 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 n [sqlite3_step(
1f550 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 )], unless.** as
1f560 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 stated in the p
1f570 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 revious paragrap
1f580 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 h, sqlite3_step(
1f590 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c ) invokes.** sql
1f5a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1f5b0 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 ) to reprepare a
1f5c0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 statement after
1f5d0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 a schema change
1f5e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
1f5f0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
1f600 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 . sqlite3*,. i
1f610 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 nt (*xAuth)(void
1f620 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 *,int,const char
1f630 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f *,const char*,co
1f640 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
1f650 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a char*),. void *
1f660 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a pUserData.);../*
1f670 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
1f680 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 thorizer Return
1f690 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Codes.**.** The
1f6a0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
1f6b0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 horizer | author
1f6c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 izer callback fu
1f6d0 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 nction] must.**
1f6e0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 return either [S
1f6f0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 QLITE_OK] or one
1f700 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f of these two co
1f710 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 nstants in order
1f720 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 .** to signal SQ
1f730 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 Lite whether or
1f740 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 not the action i
1f750 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 s permitted. Se
1f760 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 e the.** [sqlite
1f770 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
1f780 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f | authorizer do
1f790 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 cumentation] for
1f7a0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 additional.** i
1f7b0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
1f7c0 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 * Note that SQLI
1f7d0 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 TE_IGNORE is als
1f7e0 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e o used as a [con
1f7f0 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e flict resolution
1f800 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e mode].** return
1f810 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c ed from the [sql
1f820 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e ite3_vtab_on_con
1f830 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 flict()] interfa
1f840 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ce..*/.#define S
1f850 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 QLITE_DENY 1
1f860 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 /* Abort the SQ
1f870 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 L statement with
1f880 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 an error */.#de
1f890 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f fine SQLITE_IGNO
1f8a0 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 RE 2 /* Don't
1f8b0 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 allow access, bu
1f8c0 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 t don't generate
1f8d0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a an error */../*
1f8e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
1f8f0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 thorizer Action
1f900 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Codes.**.** The
1f910 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
1f920 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 horizer()] inter
1f930 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 face registers a
1f940 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1f950 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e on.** that is in
1f960 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 voked to authori
1f970 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 ze certain SQL s
1f980 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 tatement actions
1f990 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 . The.** second
1f9a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1f9b0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
1f9c0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 integer code th
1f9d0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 at specifies.**
1f9e0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 what action is b
1f9f0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e eing authorized.
1fa00 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 These are the
1fa10 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 integer action c
1fa20 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 odes that.** the
1fa30 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1fa40 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 back may be pass
1fa50 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
1fa60 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 action code valu
1fa70 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 es signify what
1fa80 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f kind of operatio
1fa90 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 n is to be.** au
1faa0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 thorized. The 3
1fab0 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d rd and 4th param
1fac0 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 eters to the aut
1fad0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 horization.** ca
1fae0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
1faf0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 will be paramete
1fb00 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e rs or NULL depen
1fb10 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 ding on which of
1fb20 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 these.** codes
1fb30 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 is used as the s
1fb40 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e econd parameter.
1fb50 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 ^(The 5th para
1fb60 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 meter to the.**
1fb70 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1fb80 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ack is the name
1fb90 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
1fba0 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c ("main", "temp",
1fbb0 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 .** etc.) if app
1fbc0 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 licable.)^ ^The
1fbd0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6th parameter t
1fbe0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 o the authorizer
1fbf0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
1fc00 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
1fc10 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 inner-most trigg
1fc20 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 er or view that
1fc30 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
1fc40 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 or.** the access
1fc50 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c attempt or NULL
1fc60 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 if this access
1fc70 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 attempt is direc
1fc80 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d tly from.** top-
1fc90 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a level SQL code..
1fca0 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */./************
1fcb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1fcc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 ***************
1fcd0 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 3rd ************
1fce0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 4th ***********
1fcf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1fd00 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 _CREATE_INDEX
1fd10 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 1 /* In
1fd20 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
1fd30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1fd40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1fd50 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 CREATE_TABLE
1fd60 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 2 /* Tab
1fd70 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
1fd80 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1fd90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1fda0 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 REATE_TEMP_INDEX
1fdb0 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 3 /* Inde
1fdc0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
1fdd0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
1fde0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
1fdf0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 EATE_TEMP_TABLE
1fe00 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 4 /* Table
1fe10 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1fe20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1fe30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
1fe40 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 ATE_TEMP_TRIGGER
1fe50 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 5 /* Trigge
1fe60 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
1fe70 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1fe80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
1fe90 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 TE_TEMP_VIEW
1fea0 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6 /* View Na
1feb0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
1fec0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1fed0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1fee0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 E_TRIGGER
1fef0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 7 /* Trigger
1ff00 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
1ff10 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
1ff20 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1ff30 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 _VIEW
1ff40 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 8 /* View Name
1ff50 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
1ff60 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1ff70 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 e SQLITE_DELETE
1ff80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 9
1ff90 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1ffa0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1ffb0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1ffc0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 SQLITE_DROP_IND
1ffd0 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 EX 10
1ffe0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
1fff0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
20000 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
20010 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c SQLITE_DROP_TABL
20020 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 E 11
20030 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
20040 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
20050 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
20060 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
20070 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 INDEX 12
20080 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
20090 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
200a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
200b0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 LITE_DROP_TEMP_T
200c0 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f ABLE 13 /
200d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
200e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
200f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
20100 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 ITE_DROP_TEMP_TR
20110 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a IGGER 14 /*
20120 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
20130 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
20140 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20150 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 TE_DROP_TEMP_VIE
20160 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 W 15 /*
20170 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
20180 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
20190 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
201a0 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 E_DROP_TRIGGER
201b0 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 16 /* T
201c0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
201d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
201e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
201f0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 _DROP_VIEW
20200 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 17 /* Vi
20210 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
20220 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
20230 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20240 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 INSERT
20250 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 18 /* Tab
20260 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
20270 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
20280 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
20290 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 RAGMA
202a0 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 19 /* Prag
202b0 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 ma Name 1st
202c0 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 arg or NULL */.#
202d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
202e0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AD
202f0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 /* Table
20300 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d Name Colum
20310 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 n Name */.#d
20320 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c efine SQLITE_SEL
20330 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 ECT
20340 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 21 /* NULL
20350 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 NULL
20360 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
20370 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e fine SQLITE_TRAN
20380 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 SACTION
20390 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 22 /* Operati
203a0 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 on NULL
203b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
203c0 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 ine SQLITE_UPDAT
203d0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
203e0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 23 /* Table Na
203f0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e me Column N
20400 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
20410 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 ne SQLITE_ATTACH
20420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
20430 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 4 /* Filename
20440 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
20450 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
20460 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 e SQLITE_DETACH
20470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 25
20480 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e /* Database N
20490 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 ame NULL
204a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
204b0 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 SQLITE_ALTER_TA
204c0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 BLE 26
204d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 /* Database Na
204e0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 me Table Name
204f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
20500 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 SQLITE_REINDEX
20510 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 27
20520 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
20530 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
20540 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
20550 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 QLITE_ANALYZE
20560 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 28
20570 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
20580 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
20590 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
205a0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 LITE_CREATE_VTAB
205b0 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f LE 29 /
205c0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
205d0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 Module Name
205e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
205f0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 ITE_DROP_VTABLE
20600 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 30 /*
20610 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
20620 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 Module Name
20630 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20640 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 TE_FUNCTION
20650 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 31 /*
20660 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
20670 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 Function Name
20680 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20690 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 E_SAVEPOINT
206a0 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 32 /* O
206b0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 peration S
206c0 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a avepoint Name *
206d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
206e0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 _COPY
206f0 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 0 /* No
20700 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a longer used */.
20710 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
20720 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 ECURSIVE
20730 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 33 /* NULL
20740 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c NULL
20750 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a */..
20760 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
20770 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 Tracing And Prof
20780 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a iling Functions.
20790 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
207a0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 e3.**.** These r
207b0 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 outines register
207c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
207d0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 ons that can be
207e0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 used for.** trac
207f0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e ing and profilin
20800 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 g the execution
20810 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 of SQL statement
20820 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 s..**.** ^The ca
20830 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
20840 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 registered by sq
20850 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 lite3_trace() is
20860 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 invoked at.** v
20870 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 arious times whe
20880 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
20890 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 nt is being run
208a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 by [sqlite3_step
208b0 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ()]..** ^The sql
208c0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c ite3_trace() cal
208d0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
208e0 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 with a UTF-8 re
208f0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a ndering of the.*
20900 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 * SQL statement
20910 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 text as the stat
20920 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 ement first begi
20930 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a ns executing..**
20940 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 ^(Additional sq
20950 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 lite3_trace() ca
20960 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 llbacks might oc
20970 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 cur.** as each t
20980 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 riggered subprog
20990 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 ram is entered.
209a0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 The callbacks f
209b0 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 or triggers.** c
209c0 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 ontain a UTF-8 S
209d0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 QL comment that
209e0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 identifies the t
209f0 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 rigger.)^.**.**
20a00 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 The [SQLITE_TRAC
20a10 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f E_SIZE_LIMIT] co
20a20 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
20a30 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
20a40 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 limit.** the le
20a50 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 ngth of [bound p
20a60 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 arameter] expans
20a70 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 ion in the outpu
20a80 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 t of sqlite3_tra
20a90 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ce()..**.** ^The
20aa0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
20ab0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 on registered by
20ac0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 sqlite3_profile
20ad0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a () is invoked.**
20ae0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 as each SQL sta
20af0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e tement finishes.
20b00 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 ^The profile c
20b10 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 allback contains
20b20 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c .** the original
20b30 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 statement text
20b40 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 and an estimate
20b50 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 of wall-clock ti
20b60 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e me.** of how lon
20b70 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 g that statement
20b80 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e took to run. ^
20b90 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c The profile call
20ba0 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 back.** time is
20bb0 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f in units of nano
20bc0 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 seconds, however
20bd0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 the current imp
20be0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 lementation.** i
20bf0 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f s only capable o
20c00 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 f millisecond re
20c10 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 solution so the
20c20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 six least signif
20c30 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 icant.** digits
20c40 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 in the time are
20c50 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 meaningless. Fu
20c60 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
20c70 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 SQLite.** might
20c80 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 provide greater
20c90 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 resolution on t
20ca0 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c he profiler call
20cb0 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 back. The.** sq
20cc0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 lite3_profile()
20cd0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 function is cons
20ce0 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e idered experimen
20cf0 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 tal and is.** su
20d00 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
20d10 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f in future versio
20d20 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f ns of SQLite..*/
20d30 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 .void *sqlite3_t
20d40 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 race(sqlite3*, v
20d50 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 oid(*xTrace)(voi
20d60 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c d*,const char*),
20d70 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f void*);.SQLITE_
20d80 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 EXPERIMENTAL voi
20d90 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 d *sqlite3_profi
20da0 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 le(sqlite3*,.
20db0 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 void(*xProfile)(
20dc0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 void*,const char
20dd0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 *,sqlite3_uint64
20de0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ), void*);../*.*
20df0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 * CAPI3REF: Quer
20e00 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 y Progress Callb
20e10 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 acks.** METHOD:
20e20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
20e30 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 he sqlite3_progr
20e40 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c ess_handler(D,N,
20e50 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 X,P) interface c
20e60 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 auses the callba
20e70 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 ck.** function X
20e80 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 to be invoked p
20e90 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 eriodically duri
20ea0 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 ng long running
20eb0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c calls to.** [sql
20ec0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 ite3_exec()], [s
20ed0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 qlite3_step()] a
20ee0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f nd [sqlite3_get_
20ef0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 table()] for.**
20f00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
20f10 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 ion D. An examp
20f20 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a le use for this.
20f30 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
20f40 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 to keep a GUI up
20f50 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c dated during a l
20f60 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a arge query..**.*
20f70 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 * ^The parameter
20f80 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 P is passed thr
20f90 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 ough as the only
20fa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
20fb0 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 e .** callback f
20fc0 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 unction X. ^The
20fd0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 parameter N is
20fe0 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 the approximate
20ff0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 number of .** [v
21000 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 irtual machine i
21010 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 nstructions] tha
21020 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 t are evaluated
21030 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 between successi
21040 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e ve.** invocation
21050 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 s of the callbac
21060 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c k X. ^If N is l
21070 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 ess than one the
21080 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a n the progress.*
21090 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 * handler is dis
210a0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e abled..**.** ^On
210b0 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 ly a single prog
210c0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 ress handler may
210d0 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f be defined at o
210e0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b ne time per.** [
210f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
21100 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 ion]; setting a
21110 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e new progress han
21120 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 dler cancels the
21130 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 .** old one. ^S
21140 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 etting parameter
21150 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 X to NULL disab
21160 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 les the progress
21170 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 handler..** ^Th
21180 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
21190 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 er is also disab
211a0 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e led by setting N
211b0 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 to a value less
211c0 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a .** than 1..**.*
211d0 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 * ^If the progre
211e0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 ss callback retu
211f0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
21200 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a e operation is.*
21210 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 * interrupted.
21220 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e This feature can
21230 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c be used to impl
21240 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 ement a.** "Canc
21250 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 el" button on a
21260 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 GUI progress dia
21270 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 log box..**.** T
21280 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
21290 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 ler callback mus
212a0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
212b0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
212c0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
212d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
212e0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 at invoked the p
212f0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e rogress handler.
21300 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
21310 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
21320 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
21330 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
21340 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
21350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
21360 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
21370 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
21380 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
21390 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 h..**.*/.void sq
213a0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 lite3_progress_h
213b0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
213c0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 int, int(*)(voi
213d0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a d*), void*);../*
213e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 .** CAPI3REF: Op
213f0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 ening A New Data
21400 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a base Connection.
21410 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 ** CONSTRUCTOR:
21420 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
21430 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 hese routines op
21440 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 en an SQLite dat
21450 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 abase file as sp
21460 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a ecified by the .
21470 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 ** filename argu
21480 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e ment. ^The filen
21490 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ame argument is
214a0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
214b0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 TF-8 for.** sqli
214c0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 te3_open() and s
214d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
214e0 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 and as UTF-16 i
214f0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
21500 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 e.** order for s
21510 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e qlite3_open16().
21520 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 ^(A [database c
21530 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
21540 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 e is usually.**
21550 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 returned in *ppD
21560 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 b, even if an er
21570 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 ror occurs. The
21580 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 only exception
21590 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 is that.** if SQ
215a0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 Lite is unable t
215b0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 o allocate memor
215c0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 y to hold the [s
215d0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a qlite3] object,.
215e0 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 ** a NULL will b
215f0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a e written into *
21600 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 ppDb instead of
21610 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
21620 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 [sqlite3].** ob
21630 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 ject.)^ ^(If the
21640 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
21650 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 ned (and/or crea
21660 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c ted) successfull
21670 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 y, then.** [SQLI
21680 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e TE_OK] is return
21690 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 ed. Otherwise a
216a0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
216b0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 s returned.)^ ^T
216c0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 he.** [sqlite3_e
216d0 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c rrmsg()] or [sql
216e0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d ite3_errmsg16()]
216f0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 routines can be
21700 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a used to obtain.
21710 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 ** an English la
21720 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 nguage descripti
21730 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 on of the error
21740 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c following a fail
21750 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 ure of any.** of
21760 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 the sqlite3_ope
21770 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a n() routines..**
21780 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 .** ^The default
21790 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 encoding will b
217a0 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 e UTF-8 for data
217b0 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 bases created us
217c0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f ing.** sqlite3_o
217d0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
217e0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 _open_v2(). ^Th
217f0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 e default encodi
21800 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 ng for databases
21810 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e .** created usin
21820 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 g sqlite3_open16
21830 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 () will be UTF-1
21840 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 6 in the native
21850 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a byte order..**.*
21860 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * Whether or not
21870 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
21880 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e when it is open
21890 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a ed, resources.**
218a0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
218b0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
218c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
218d0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 e should be rele
218e0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 ased by.** passi
218f0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
21900 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 3_close()] when
21910 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 it is no longer
21920 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
21930 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e The sqlite3_open
21940 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 _v2() interface
21950 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
21960 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 e3_open().** exc
21970 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 ept that it acce
21980 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e pts two addition
21990 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f al parameters fo
219a0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e r additional con
219b0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 trol.** over the
219c0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
219d0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 nnection. ^(The
219e0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
219f0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f to.** sqlite3_o
21a00 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b pen_v2() can tak
21a10 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 e one of.** the
21a20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 following three
21a30 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c values, optional
21a40 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 ly combined with
21a50 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 the .** [SQLITE
21a60 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 _OPEN_NOMUTEX],
21a70 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c [SQLITE_OPEN_FUL
21a80 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 LMUTEX], [SQLITE
21a90 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
21aa0 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f E],.** [SQLITE_O
21ab0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
21ac0 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 ], and/or [SQLIT
21ad0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 E_OPEN_URI] flag
21ae0 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a s:)^.**.** <dl>.
21af0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 ** ^(<dt>[SQLITE
21b00 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c _OPEN_READONLY]<
21b10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
21b20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
21b30 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 ed in read-only
21b40 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 mode. If the da
21b50 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a tabase does not.
21b60 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ** already exist
21b70 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 , an error is re
21b80 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a turned.</dd>)^.*
21b90 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 *.** ^(<dt>[SQLI
21ba0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
21bb0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 E]</dt>.** <dd>T
21bc0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
21bd0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e pened for readin
21be0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 g and writing if
21bf0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 possible, or re
21c00 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 ading.** only if
21c10 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 the file is wri
21c20 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 te protected by
21c30 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
21c40 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 stem. In either
21c50 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 .** case the dat
21c60 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 abase must alrea
21c70 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 dy exist, otherw
21c80 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 ise an error is
21c90 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e returned.</dd>)^
21ca0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 .**.** ^(<dt>[SQ
21cb0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
21cc0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
21cd0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e PEN_CREATE]</dt>
21ce0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
21cf0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
21d00 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 or reading and w
21d10 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 riting, and is c
21d20 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 reated if.** it
21d30 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 does not already
21d40 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 exist. This is
21d50 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 the behavior tha
21d60 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 t is always used
21d70 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
21d80 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
21d90 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 e3_open16().</dd
21da0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a >)^.** </dl>.**.
21db0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 ** If the 3rd pa
21dc0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
21dd0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
21de0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a not one of the.*
21df0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 * combinations s
21e00 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f hown above optio
21e10 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 nally combined w
21e20 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 ith other.** [SQ
21e30 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
21e40 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e LY | SQLITE_OPEN
21e50 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e _* bits].** then
21e60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
21e70 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
21e80 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 * ^If the [SQLIT
21e90 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 E_OPEN_NOMUTEX]
21ea0 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 flag is set, the
21eb0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
21ec0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 onnection.** ope
21ed0 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d ns in the multi-
21ee0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e thread [threadin
21ef0 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 g mode] as long
21f00 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 as the single-th
21f10 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 read.** mode has
21f20 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 not been set at
21f30 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 compile-time or
21f40 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 start-time. ^I
21f50 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 f the.** [SQLITE
21f60 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d _OPEN_FULLMUTEX]
21f70 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 flag is set the
21f80 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
21f90 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a onnection opens.
21fa0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c ** in the serial
21fb0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 ized [threading
21fc0 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e mode] unless sin
21fd0 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a gle-thread was.*
21fe0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c * previously sel
21ff0 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 ected at compile
22000 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 -time or start-t
22010 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ime..** ^The [SQ
22020 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
22030 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 CACHE] flag caus
22040 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
22050 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 connection to be
22060 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 .** eligible to
22070 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 use [shared cach
22080 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c e mode], regardl
22090 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
220a0 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 r not shared.**
220b0 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 cache is enabled
220c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
220d0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 enable_shared_ca
220e0 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a che()]. ^The.**
220f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 [SQLITE_OPEN_PR
22100 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 IVATECACHE] flag
22110 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 causes the data
22120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
22130 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 to not.** partic
22140 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 ipate in [shared
22150 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 cache mode] eve
22160 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c n if it is enabl
22170 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ed..**.** ^The f
22180 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
22190 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
221a0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 v2() is the name
221b0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
221c0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 te3_vfs] object
221d0 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 that defines the
221e0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
221f0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 m interface that
22200 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 .** the new data
22210 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
22220 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 should use. ^If
22230 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
22240 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 meter is.** a NU
22250 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
22260 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
22270 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
22280 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
22290 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ^If the filename
222a0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 is ":memory:",
222b0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 then a private,
222c0 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d temporary in-mem
222d0 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 ory database.**
222e0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 is created for t
222f0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 he connection.
22300 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 ^This in-memory
22310 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 database will va
22320 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 nish when.** the
22330 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
22340 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 tion is closed.
22350 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 Future versions
22360 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 of SQLite might
22370 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 .** make use of
22380 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 additional speci
22390 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 al filenames tha
223a0 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 t begin with the
223b0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a ":" character..
223c0 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 ** It is recomme
223d0 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 nded that when a
223e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 database filena
223f0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 me actually does
22400 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 begin with.** a
22410 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 ":" character y
22420 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 ou should prefix
22430 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 the filename wi
22440 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 th a pathname su
22450 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f ch as.** "./" to
22460 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 avoid ambiguity
22470 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
22480 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 filename is an e
22490 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 mpty string, the
224a0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d n a private, tem
224b0 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 porary.** on-dis
224c0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 k database will
224d0 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 be created. ^Th
224e0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 is private datab
224f0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 ase will be.** a
22500 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c utomatically del
22510 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 eted as soon as
22520 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
22530 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
22540 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 d..**.** [[URI f
22550 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 ilenames in sqli
22560 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 te3_open()]] <h3
22570 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f >URI Filenames</
22580 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 h3>.**.** ^If [U
22590 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 RI filename] int
225a0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 erpretation is e
225b0 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 nabled, and the
225c0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
225d0 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 t.** begins with
225e0 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 "file:", then t
225f0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 he filename is i
22600 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
22610 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c URI. ^URI.** fil
22620 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 ename interpreta
22630 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 tion is enabled
22640 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f if the [SQLITE_O
22650 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 PEN_URI] flag is
22660 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 .** set in the f
22670 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 ourth argument t
22680 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
22690 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 2(), or if it ha
226a0 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 s.** been enable
226b0 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 d globally using
226c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
226d0 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 FIG_URI] option
226e0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c with the.** [sql
226f0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d ite3_config()] m
22700 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 ethod or by the
22710 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d [SQLITE_USE_URI]
22720 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
22730 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 tion..** As of S
22740 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
22750 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 7.7, URI filenam
22760 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e e interpretation
22770 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a is turned off.*
22780 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 * by default, bu
22790 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 t future release
227a0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
227b0 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c t enable URI fil
227c0 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 ename.** interpr
227d0 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 etation by defau
227e0 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 lt. See "[URI f
227f0 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 ilenames]" for a
22800 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
22810 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
22820 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 URI filenames ar
22830 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 e parsed accordi
22840 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 ng to RFC 3986.
22850 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 ^If the URI cont
22860 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f ains an.** autho
22870 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 rity, then it mu
22880 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 st be either an
22890 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 empty string or
228a0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 the string .** "
228b0 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 localhost". ^If
228c0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 the authority is
228d0 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 not an empty st
228e0 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f ring or "localho
228f0 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f st", an .** erro
22900 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f r is returned to
22910 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 the caller. ^Th
22920 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f e fragment compo
22930 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 nent of a URI, i
22940 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 f .** present, i
22950 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a s ignored..**.**
22960 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 ^SQLite uses th
22970 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 e path component
22980 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 of the URI as t
22990 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
229a0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 isk file.** whic
229b0 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 h contains the d
229c0 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 atabase. ^If the
229d0 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 path begins wit
229e0 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 h a '/' characte
229f0 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 r, .** then it i
22a00 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
22a10 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 an absolute pat
22a20 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 h. ^If the path
22a30 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a does not begin .
22a40 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d ** with a '/' (m
22a50 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 eaning that the
22a60 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f authority sectio
22a70 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f n is omitted fro
22a80 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 m the URI).** th
22a90 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 en the path is i
22aa0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
22ab0 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a relative path. .
22ac0 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c ** ^(On windows,
22ad0 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f the first compo
22ae0 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c nent of an absol
22af0 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 ute path .** is
22b00 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 a drive specific
22b10 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 ation (e.g. "C:"
22b20 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 ).)^.**.** [[cor
22b30 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 e URI query para
22b40 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 meters]].** The
22b50 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 query component
22b60 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e of a URI may con
22b70 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 tain parameters
22b80 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 that are interpr
22b90 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 eted.** either b
22ba0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c y SQLite itself,
22bb0 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 or by a [VFS |
22bc0 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 custom VFS imple
22bd0 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 mentation]..** S
22be0 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 QLite and its bu
22bf0 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 ilt-in [VFSes] i
22c00 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 nterpret the.**
22c10 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 following query
22c20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a parameters:.**.*
22c30 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e * <ul>.** <li>
22c40 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 <b>vfs</b>: ^Th
22c50 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 e "vfs" paramete
22c60 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f r may be used to
22c70 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d specify the nam
22c80 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 e of.** a VF
22c90 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 S object that pr
22ca0 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 ovides the opera
22cb0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 ting system inte
22cc0 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c rface that shoul
22cd0 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 d.** be used
22ce0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 to access the d
22cf0 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 atabase file on
22d00 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f disk. ^If this o
22d10 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a ption is set to.
22d20 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 ** an empty
22d30 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 string the defau
22d40 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 lt VFS object is
22d50 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 used. ^Specifyi
22d60 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a ng an unknown.**
22d70 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 VFS is an e
22d80 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 rror. ^If sqlite
22d90 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 3_open_v2() is u
22da0 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 sed and the vfs
22db0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 option is.**
22dc0 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 present, then t
22dd0 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 he VFS specified
22de0 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 by the option t
22df0 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 akes precedence
22e00 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 over.** the
22e10 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
22e20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
22e30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
22e40 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a open_v2()..**.**
22e50 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c <li> <b>mode<
22e60 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 /b>: ^(The mode
22e70 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
22e80 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 set to either "
22e90 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 ro", "rw",.**
22ea0 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d "rwc", or "mem
22eb0 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 ory". Attempting
22ec0 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e to set it to an
22ed0 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 y other value is
22ee0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 .** an error
22ef0 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 )^. .** ^If
22f00 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 "ro" is specifie
22f10 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 d, then the data
22f20 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
22f30 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a or read-only .**
22f40 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 access, jus
22f50 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c t as if the [SQL
22f60 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
22f70 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e Y] flag had been
22f80 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 set in the .**
22f90 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 third argume
22fa0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 nt to sqlite3_op
22fb0 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 en_v2(). ^If the
22fc0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 mode option is
22fd0 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 set to .** "
22fe0 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 rw", then the da
22ff0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
23000 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 for read-write
23010 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 (but not create)
23020 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c .** access,
23030 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 as if SQLITE_OP
23040 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 EN_READWRITE (bu
23050 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 t not SQLITE_OPE
23060 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a N_CREATE) had .*
23070 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 * been set.
23080 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 ^Value "rwc" is
23090 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 equivalent to se
230a0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 tting both .**
230b0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 SQLITE_OPEN_R
230c0 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c EADWRITE and SQL
230d0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e ITE_OPEN_CREATE.
230e0 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f ^If the mode o
230f0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 ption is.**
23100 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 set to "memory"
23110 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d then a pure [in-
23120 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d memory database]
23130 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 that never read
23140 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 s.** or writ
23150 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 es from disk is
23160 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 used. ^It is an
23170 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 error to specify
23180 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 a value for.**
23190 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 the mode par
231a0 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c ameter that is l
231b0 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 ess restrictive
231c0 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 than that specif
231d0 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 ied by.** th
231e0 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 e flags passed i
231f0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 n the third para
23200 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
23210 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a _open_v2()..**.*
23220 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 * <li> <b>cach
23230 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 e</b>: ^The cach
23240 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 e parameter may
23250 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 be set to either
23260 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 "shared" or.**
23270 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e "private". ^
23280 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 Setting it to "s
23290 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 hared" is equiva
232a0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 lent to setting
232b0 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 the.** SQLIT
232c0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
232d0 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c HE bit in the fl
232e0 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 ags argument pas
232f0 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 sed to.** sq
23300 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
23310 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 ^Setting the ca
23320 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f che parameter to
23330 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a "private" is .*
23340 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 * equivalent
23350 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 to setting the
23360 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
23370 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a ATECACHE bit..**
23380 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 ^If sqlite3
23390 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 _open_v2() is us
233a0 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 ed and the "cach
233b0 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 e" parameter is
233c0 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 present in.**
233d0 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 a URI filename
233e0 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 , its value over
233f0 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 rides any behavi
23400 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 or requested by
23410 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 setting.** S
23420 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
23430 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 TECACHE or SQLIT
23440 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
23450 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 HE flag..**.**
23460 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e <li> <b>psow</b>
23470 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 : ^The psow para
23480 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 meter indicates
23490 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
234a0 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 he.** [power
234b0 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 safe overwrite]
234c0 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 property does or
234d0 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 does not apply
234e0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 to the.** st
234f0 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 orage media on w
23500 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73 hich the databas
23510 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a e file resides..
23520 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e **.** <li> <b>n
23530 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 olock</b>: ^The
23540 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 nolock parameter
23550 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 is a boolean qu
23560 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ery parameter.**
23570 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65 which if se
23580 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 t disables file
23590 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 locking in rollb
235a0 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 ack journal mode
235b0 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 s. This.**
235c0 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 is useful for ac
235d0 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 cessing a databa
235e0 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 se on a filesyst
235f0 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 em that does not
23600 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 .** support
23610 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f locking. Cautio
23620 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 n: Database cor
23630 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 ruption might re
23640 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 sult if two.**
23650 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 or more proce
23660 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 sses write to th
23670 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
23680 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 and any one of t
23690 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 hose.** proc
236a0 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 esses uses noloc
236b0 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e k=1..**.** <li>
236c0 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 <b>immutable</b
236d0 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c >: ^The immutabl
236e0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 e parameter is a
236f0 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a boolean query.*
23700 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 * parameter
23710 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 that indicates t
23720 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 hat the database
23730 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 file is stored
23740 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f on.** read-o
23750 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 nly media. ^Whe
23760 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 n immutable is s
23770 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d et, SQLite assum
23780 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 es that the.**
23790 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 database file
237a0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 cannot be chang
237b0 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 ed, even by a pr
237c0 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65 ocess with highe
237d0 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 r.** privile
237e0 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 ge, and so the d
237f0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
23800 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 d read-only and
23810 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 all locking.**
23820 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 and change de
23830 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 tection is disab
23840 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 led. Caution: S
23850 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 etting the immut
23860 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 able.** prop
23870 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 erty on a databa
23880 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 se file that doe
23890 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 s in fact change
238a0 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 can result.**
238b0 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 in incorrect
238c0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e query results an
238d0 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 d/or [SQLITE_COR
238e0 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a RUPT] errors..**
238f0 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b See also: [
23900 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d SQLITE_IOCAP_IMM
23910 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 UTABLE]..**
23920 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a .** </ul>.**.*
23930 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e * ^Specifying an
23940 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 unknown paramet
23950 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 er in the query
23960 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 component of a U
23970 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 RI is not an.**
23980 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 error. Future v
23990 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
239a0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 e might understa
239b0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 nd additional qu
239c0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ery.** parameter
239d0 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 s. See "[query
239e0 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 parameters with
239f0 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 special meaning
23a00 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a to SQLite]" for.
23a10 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e ** additional in
23a20 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
23a30 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 [[URI filename
23a40 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 examples]] <h3>U
23a50 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d RI filename exam
23a60 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 ples</h3>.**.**
23a70 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 <table border="1
23a80 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 " align=center c
23a90 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a ellpadding=5>.**
23aa0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 <tr><th> URI fi
23ab0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 lenames <th> Res
23ac0 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ults.** <tr><td>
23ad0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 file:data.db <t
23ae0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
23af0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 Open the file "d
23b00 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 ata.db" in the c
23b10 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 urrent directory
23b20 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 ..** <tr><td> fi
23b30 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 le:/home/fred/da
23b40 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 ta.db<br>.**
23b50 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f file:///ho
23b60 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 me/fred/data.db
23b70 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <br> .**
23b80 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f file://localho
23b90 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 st/home/fred/dat
23ba0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a a.db <br> <td> .
23bb0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e ** Open
23bc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
23bd0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 le "/home/fred/d
23be0 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e ata.db"..** <tr>
23bf0 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b <td> file://dark
23c00 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 star/home/fred/d
23c10 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 ata.db <td> .**
23c20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f An erro
23c30 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 r. "darkstar" is
23c40 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 not a recognize
23c50 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 d authority..**
23c60 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 <tr><td style="w
23c70 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 hite-space:nowra
23c80 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 p"> .**
23c90 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 file:///C:/Docu
23ca0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 ments%20and%20Se
23cb0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b ttings/fred/Desk
23cc0 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 top/data.db.**
23cd0 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 <td> Windows
23ce0 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 only: Open the f
23cf0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e ile "data.db" on
23d00 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 fred's desktop
23d10 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 on drive.**
23d20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 C:. Note th
23d30 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 at the %20 escap
23d40 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d ing in this exam
23d50 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 ple is not stric
23d60 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 tly .**
23d70 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 necessary - spa
23d80 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 ce characters ca
23d90 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 n be used litera
23da0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 lly.**
23db0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 in URI filenames
23dc0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 ..** <tr><td> fi
23dd0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d le:data.db?mode=
23de0 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 ro&cache=private
23df0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
23e00 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 Open file "da
23e10 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 ta.db" in the cu
23e20 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 rrent directory
23e30 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 for read-only ac
23e40 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 cess..**
23e50 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 Regardless of
23e60 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 whether or not s
23e70 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 hared-cache mode
23e80 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a is enabled by.*
23e90 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 * defau
23ea0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 lt, use a privat
23eb0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e e cache..** <tr>
23ec0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f <td> file:/home/
23ed0 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 fred/data.db?vfs
23ee0 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 =unix-dotfile <t
23ef0 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f d>.** O
23f00 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f pen file "/home/
23f10 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 fred/data.db". U
23f20 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 se the special V
23f30 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 FS "unix-dotfile
23f40 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ".** th
23f50 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 at uses dot-file
23f60 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f s in place of po
23f70 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 six advisory loc
23f80 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 king..** <tr><td
23f90 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d > file:data.db?m
23fa0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 ode=readonly <td
23fb0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 > .** A
23fc0 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e n error. "readon
23fd0 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c ly" is not a val
23fe0 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 id option for th
23ff0 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 e "mode" paramet
24000 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a er..** </table>.
24010 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 **.** ^URI hexad
24020 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 ecimal escape se
24030 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 quences (%HH) ar
24040 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 e supported with
24050 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a in the path and.
24060 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 ** query compone
24070 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 nts of a URI. A
24080 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 hexadecimal esca
24090 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 pe sequence cons
240a0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 ists of a.** per
240b0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 cent sign - "%"
240c0 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 - followed by ex
240d0 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 actly two hexade
240e0 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a cimal digits .**
240f0 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f specifying an o
24100 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 ctet value. ^Bef
24110 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 ore the path or
24120 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 query components
24130 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c of a.** URI fil
24140 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 ename are interp
24150 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 reted, they are
24160 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 encoded using UT
24170 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 F-8 and all .**
24180 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 hexadecimal esca
24190 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 pe sequences rep
241a0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c laced by a singl
241b0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e e byte containin
241c0 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 g the.** corresp
241d0 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 onding octet. If
241e0 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 this process ge
241f0 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c nerates an inval
24200 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e id UTF-8 encodin
24210 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 g,.** the result
24220 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
24230 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 .**.** <b>Note t
24240 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a o Windows users:
24250 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 </b> The encodi
24260 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 ng used for the
24270 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
24280 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f t.** of sqlite3_
24290 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
242a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 e3_open_v2() mus
242b0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 t be UTF-8, not
242c0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 whatever.** code
242d0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c page is currentl
242e0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 y defined. File
242f0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 names containing
24300 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a international.*
24310 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 * characters mus
24320 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 t be converted t
24330 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f o UTF-8 prior to
24340 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e passing them in
24350 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 to.** sqlite3_op
24360 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f en() or sqlite3_
24370 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a open_v2()..**.**
24380 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 <b>Note to Wind
24390 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 ows Runtime user
243a0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 s:</b> The temp
243b0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 orary directory
243c0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 must be set.** p
243d0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 rior to calling
243e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
243f0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
24400 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 2(). Otherwise,
24410 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 various.** feat
24420 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 ures that requir
24430 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d e the use of tem
24440 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 porary files may
24450 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 fail..**.** See
24460 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
24470 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a temp_directory].
24480 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f */.int sqlite3_o
24490 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 pen(. const cha
244a0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f r *filename, /
244b0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
244c0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 ame (UTF-8) */.
244d0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 sqlite3 **ppDb
244e0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
244f0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
24500 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 e */.);.int sqli
24510 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f te3_open16(. co
24520 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 nst void *filena
24530 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
24540 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
24550 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 16) */. sqlite3
24560 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
24570 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
24580 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
24590 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e int sqlite3_open
245a0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 _v2(. const cha
245b0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f r *filename, /
245c0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
245d0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 ame (UTF-8) */.
245e0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c sqlite3 **ppDb,
245f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
24600 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
24610 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 e */. int flags
24620 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
24630 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e * Flags */. con
24640 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 st char *zVfs
24650 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
24660 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 VFS module to us
24670 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.);../*.** C
24680 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 API3REF: Obtain
24690 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 Values For URI P
246a0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 arameters.**.**
246b0 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 These are utilit
246c0 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 y routines, usef
246d0 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d ul to VFS implem
246e0 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 entations, that
246f0 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 check.** to see
24700 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 if a database fi
24710 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 le was a URI tha
24720 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 t contained a sp
24730 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a ecific query .**
24740 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 parameter, and
24750 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 if so obtains th
24760 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 e value of that
24770 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e query parameter.
24780 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 .**.** If F is t
24790 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
247a0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 name pointer pas
247b0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 sed into the xOp
247c0 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a en() method of .
247d0 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 ** a VFS impleme
247e0 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 ntation when the
247f0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
24800 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 to xOpen() has
24810 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 one or .** more
24820 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f of the [SQLITE_O
24830 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c PEN_URI] or [SQL
24840 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
24850 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a ] bits set and.*
24860 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 * P is the name
24870 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 of the query par
24880 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 ameter, then.**
24890 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 sqlite3_uri_para
248a0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 meter(F,P) retur
248b0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ns the value of
248c0 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 the P.** paramet
248d0 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 er if it exists
248e0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 or a NULL pointe
248f0 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 r if P does not
24900 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 appear as a .**
24910 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 query parameter
24920 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 on F. If P is a
24930 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
24940 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 of F.** has no
24950 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 explicit value,
24960 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 then sqlite3_uri
24970 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 _parameter(F,P)
24980 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 returns.** a poi
24990 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 nter to an empty
249a0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 string..**.** T
249b0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 he sqlite3_uri_b
249c0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f oolean(F,P,B) ro
249d0 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 utine assumes th
249e0 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 at P is a boolea
249f0 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 n.** parameter a
24a00 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 nd returns true
24a10 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 (1) or false (0)
24a20 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 according to th
24a30 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e e value.** of P.
24a40 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 The sqlite3_ur
24a50 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 i_boolean(F,P,B)
24a60 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
24a70 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 true (1) if the
24a80 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 .** value of que
24a90 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 ry parameter P i
24aa0 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 s one of "yes",
24ab0 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 "true", or "on"
24ac0 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f in any.** case o
24ad0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 r if the value b
24ae0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e egins with a non
24af0 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 -zero number. T
24b00 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 he .** sqlite3_u
24b10 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
24b20 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 ) routines retur
24b30 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 ns false (0) if
24b40 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 the value of.**
24b50 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 query parameter
24b60 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 P is one of "no"
24b70 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f , "false", or "o
24b80 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 ff" in any case
24b90 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c or.** if the val
24ba0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 ue begins with a
24bb0 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 numeric zero.
24bc0 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 If P is not a qu
24bd0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ery.** parameter
24be0 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 on F or if the
24bf0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f value of P is do
24c00 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 es not match any
24c10 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 of the.** above
24c20 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 , then sqlite3_u
24c30 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
24c40 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 ) returns (B!=0)
24c50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
24c60 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c te3_uri_int64(F,
24c70 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e P,D) routine con
24c80 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 verts the value
24c90 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 of P into a.** 6
24ca0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 4-bit signed int
24cb0 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 eger and returns
24cc0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f that integer, o
24cd0 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f r D if P does no
24ce0 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 t.** exist. If
24cf0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 the value of P i
24d00 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 s something othe
24d10 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 r than an intege
24d20 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 r, then.** zero
24d30 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
24d40 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 .** If F is a NU
24d50 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
24d60 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 sqlite3_uri_par
24d70 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 ameter(F,P) retu
24d80 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 rns NULL and.**
24d90 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c sqlite3_uri_bool
24da0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 ean(F,P,B) retur
24db0 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e ns B. If F is n
24dc0 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ot a NULL pointe
24dd0 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 r and.** is not
24de0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 a database file
24df0 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 pathname pointer
24e00 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 that SQLite pas
24e10 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 sed into the xOp
24e20 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 en.** VFS method
24e30 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
24e40 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ior of this rout
24e50 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ine is undefined
24e60 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a and probably.**
24e70 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f undesirable..*/
24e80 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
24e90 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 ite3_uri_paramet
24ea0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a er(const char *z
24eb0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 Filename, const
24ec0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 char *zParam);.i
24ed0 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 nt sqlite3_uri_b
24ee0 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 oolean(const cha
24ef0 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 r *zFile, const
24f00 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e char *zParam, in
24f10 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c t bDefault);.sql
24f20 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
24f30 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e e3_uri_int64(con
24f40 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 st char*, const
24f50 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 char*, sqlite3_i
24f60 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 nt64);.../*.** C
24f70 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 API3REF: Error C
24f80 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 odes And Message
24f90 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
24fa0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ite3.**.** ^If t
24fb0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 he most recent s
24fc0 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c qlite3_* API cal
24fd0 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 l associated wit
24fe0 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 h .** [database
24ff0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 connection] D fa
25000 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 iled, then the s
25010 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 qlite3_errcode(D
25020 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 ) interface.** r
25030 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 eturns the numer
25040 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d ic [result code]
25050 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 or [extended re
25060 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 sult code] for t
25070 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e hat.** API call.
25080 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 .** If the most
25090 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 recent API call
250a0 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a was successful,.
250b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 ** then the retu
250c0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 rn value from sq
250d0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 lite3_errcode()
250e0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
250f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
25100 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 tended_errcode()
25110 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
25120 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 the same except
25130 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 that it always
25140 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 returns the .**
25150 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
25160 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e code] even when
25170 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
25180 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 codes are.** di
25190 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 sabled..**.** ^T
251a0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 he sqlite3_errms
251b0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f g() and sqlite3_
251c0 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 errmsg16() retur
251d0 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 n English-langua
251e0 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 ge.** text that
251f0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
25200 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 ror, as either U
25210 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 TF-8 or UTF-16 r
25220 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
25230 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 ^(Memory to hold
25240 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
25250 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e ge string is man
25260 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e aged internally.
25270 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
25280 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 ion does not nee
25290 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 d to worry about
252a0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 freeing the res
252b0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c ult..** However,
252c0 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e the error strin
252d0 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 g might be overw
252e0 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f ritten or deallo
252f0 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 cated by.** subs
25300 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
25310 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
25320 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 erface functions
25330 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
25340 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 qlite3_errstr()
25350 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
25360 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 s the English-la
25370 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 nguage text.** t
25380 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 hat describes th
25390 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c e [result code],
253a0 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 as UTF-8..** ^(
253b0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 Memory to hold t
253c0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
253d0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 string is manag
253e0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a ed internally.**
253f0 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 and must not be
25400 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 freed by the ap
25410 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a plication)^..**.
25420 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 ** When the seri
25430 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
25440 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 g mode] is in us
25450 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 e, it might be t
25460 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 he.** case that
25470 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f a second error o
25480 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 ccurs on a separ
25490 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 ate thread in be
254a0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d tween.** the tim
254b0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 e of the first e
254c0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c rror and the cal
254d0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 l to these inter
254e0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 faces..** When t
254f0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 hat happens, the
25500 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 second error wi
25510 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 ll be reported s
25520 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e ince these.** in
25530 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 terfaces always
25540 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 report the most
25550 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 recent result.
25560 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 To avoid.** this
25570 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 , each thread ca
25580 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 n obtain exclusi
25590 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 ve use of the [d
255a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
255b0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f on] D.** by invo
255c0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 king [sqlite3_mu
255d0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 tex_enter]([sqli
255e0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 te3_db_mutex](D)
255f0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 ) before beginni
25600 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 ng.** to use D a
25610 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c nd invoking [sql
25620 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
25630 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 ]([sqlite3_db_mu
25640 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a tex](D)) after.*
25650 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 * all calls to t
25660 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 he interfaces li
25670 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f sted here are co
25680 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 mpleted..**.** I
25690 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 f an interface f
256a0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 ails with SQLITE
256b0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 _MISUSE, that me
256c0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 ans the interfac
256d0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 e.** was invoked
256e0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 incorrectly by
256f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e the application.
25700 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 In that case,
25710 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 the.** error cod
25720 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 e and message ma
25730 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 y or may not be
25740 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 set..*/.int sqli
25750 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 te3_errcode(sqli
25760 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 te3 *db);.int sq
25770 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
25780 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a rrcode(sqlite3 *
25790 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 db);.const char
257a0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 *sqlite3_errmsg(
257b0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 sqlite3*);.const
257c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 void *sqlite3_e
257d0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a rrmsg16(sqlite3*
257e0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
257f0 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e qlite3_errstr(in
25800 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
25810 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 REF: Prepared St
25820 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
25830 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 * KEYWORDS: {pre
25840 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d pared statement}
25850 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
25860 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 ments}.**.** An
25870 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
25880 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
25890 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 ts a single SQL
258a0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a statement that.*
258b0 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 * has been compi
258c0 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 led into binary
258d0 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 form and is read
258e0 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 y to be evaluate
258f0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f d..**.** Think o
25900 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 f each SQL state
25910 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 ment as a separa
25920 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 te computer prog
25930 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 ram. The.** ori
25940 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 ginal SQL text i
25950 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 s source code.
25960 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 A prepared state
25970 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 ment object .**
25980 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 is the compiled
25990 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c object code. Al
259a0 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f l SQL must be co
259b0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a nverted into a.*
259c0 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 * prepared state
259d0 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 ment before it c
259e0 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a an be run..**.**
259f0 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 The life-cycle
25a00 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 of a prepared st
25a10 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 atement object u
25a20 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 sually goes like
25a30 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c this:.**.** <ol
25a40 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 >.** <li> Create
25a50 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
25a60 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 atement object u
25a70 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
25a80 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 epare_v2()]..**
25a90 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 <li> Bind values
25aa0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d to [parameters]
25ab0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 using the sqlit
25ac0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 e3_bind_*().**
25ad0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a interfaces..
25ae0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 ** <li> Run the
25af0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b SQL by calling [
25b00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
25b10 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 one or more time
25b20 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 s..** <li> Reset
25b30 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
25b40 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 atement using [s
25b50 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
25b60 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 then go back.**
25b70 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 to step 2.
25b80 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 Do this zero or
25b90 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
25ba0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 <li> Destroy the
25bb0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 object using [s
25bc0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
25bd0 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a )]..** </ol>.*/.
25be0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
25bf0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 qlite3_stmt sqli
25c00 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a te3_stmt;../*.**
25c10 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 CAPI3REF: Run-t
25c20 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 ime Limits.** ME
25c30 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
25c40 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 .** ^(This inter
25c50 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 face allows the
25c60 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 size of various
25c70 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 constructs to be
25c80 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 limited.** on a
25c90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 connection by c
25ca0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e onnection basis.
25cb0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 The first para
25cc0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 meter is the.**
25cd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
25ce0 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 tion] whose limi
25cf0 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f t is to be set o
25d00 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a r queried. The.
25d10 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
25d20 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 ter is one of th
25d30 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 e [limit categor
25d40 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 ies] that define
25d50 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 a.** class of c
25d60 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
25d70 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 size limited. T
25d80 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
25d90 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 er is the.** new
25da0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 limit for that
25db0 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a construct.)^.**.
25dc0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c ** ^If the new l
25dd0 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 imit is a negati
25de0 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c ve number, the l
25df0 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 imit is unchange
25e00 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 d..** ^(For each
25e10 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 limit category
25e20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e SQLITE_LIMIT_<i>
25e30 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 NAME</i> there i
25e40 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 s a .** [limits
25e50 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 | hard upper bou
25e60 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f nd].** set at co
25e70 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 mpile-time by a
25e80 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
25e90 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b acro called.** [
25ea0 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f limits | SQLITE_
25eb0 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d MAX_<i>NAME</i>]
25ec0 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 ..** (The "_LIMI
25ed0 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 T_" in the name
25ee0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f is changed to "_
25ef0 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 MAX_".))^.** ^At
25f00 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 tempts to increa
25f10 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 se a limit above
25f20 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 its hard upper
25f30 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c bound are.** sil
25f40 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 ently truncated
25f50 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 to the hard uppe
25f60 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e r bound..**.** ^
25f70 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 Regardless of wh
25f80 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
25f90 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 limit was chang
25fa0 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c ed, the .** [sql
25fb0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e ite3_limit()] in
25fc0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
25fd0 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 the prior value
25fe0 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a of the limit..**
25ff0 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 ^Hence, to find
26000 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c the current val
26010 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 ue of a limit wi
26020 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 thout changing i
26030 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 t,.** simply inv
26040 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 oke this interfa
26050 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 ce with the thir
26060 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 d parameter set
26070 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e to -1..**.** Run
26080 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 -time limits are
26090 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
260a0 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e e in application
260b0 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a s that manage.**
260c0 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 both their own
260d0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
260e0 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 e and also datab
260f0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f ases that are co
26100 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 ntrolled.** by u
26110 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 ntrusted externa
26120 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 l sources. An e
26130 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 xample applicati
26140 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a on might be a.**
26150 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 web browser tha
26160 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 t has its own da
26170 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 tabases for stor
26180 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a ing history and.
26190 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 ** separate data
261a0 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 bases controlled
261b0 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 by JavaScript a
261c0 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e pplications down
261d0 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 loaded.** off th
261e0 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 e Internet. The
261f0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 internal databa
26200 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e ses can be given
26210 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 the.** large, d
26220 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 efault limits.
26230 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 Databases manage
26240 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f d by external so
26250 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 urces can.** be
26260 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c given much small
26270 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e er limits design
26280 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 ed to prevent a
26290 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 denial of servic
262a0 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 e.** attack. De
262b0 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 velopers might a
262c0 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 lso want to use
262d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 the [sqlite3_set
262e0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a _authorizer()].*
262f0 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 * interface to f
26300 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 urther control u
26310 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 ntrusted SQL. T
26320 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 he size of the d
26330 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 atabase.** creat
26340 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 ed by an untrust
26350 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 ed script can be
26360 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 contained using
26370 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 the.** [max_pag
26380 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 e_count] [PRAGMA
26390 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e ]..**.** New run
263a0 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 -time limit cate
263b0 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 gories may be ad
263c0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
263d0 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 leases..*/.int s
263e0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c qlite3_limit(sql
263f0 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 ite3*, int id, i
26400 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a nt newVal);../*.
26410 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
26420 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 -Time Limit Cate
26430 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 gories.** KEYWOR
26440 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 DS: {limit categ
26450 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 ory} {*limit cat
26460 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 egories}.**.** T
26470 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 hese constants d
26480 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 efine various pe
26490 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 rformance limits
264a0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 .** that can be
264b0 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 lowered at run-t
264c0 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ime using [sqlit
264d0 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 e3_limit()]..**
264e0 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 The synopsis of
264f0 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 the meanings of
26500 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 the various limi
26510 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f ts is shown belo
26520 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c w..** Additional
26530 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
26540 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 available at [li
26550 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e mits | Limits in
26560 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 SQLite]..**.**
26570 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 <dl>.** [[SQLITE
26580 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 _LIMIT_LENGTH]]
26590 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
265a0 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a IT_LENGTH</dt>.*
265b0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
265c0 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 m size of any st
265d0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 ring or BLOB or
265e0 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 table row, in by
265f0 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a tes.<dd>)^.**.**
26600 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
26610 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c SQL_LENGTH]] ^(<
26620 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
26630 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a SQL_LENGTH</dt>.
26640 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
26650 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 um length of an
26660 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 SQL statement, i
26670 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a n bytes.</dd>)^.
26680 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
26690 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 IMIT_COLUMN]] ^(
266a0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
266b0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 _COLUMN</dt>.**
266c0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
266d0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
266e0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 s in a table def
266f0 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 inition or in th
26700 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 e.** result set
26710 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 of a [SELECT] or
26720 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
26730 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
26740 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 n an index.** or
26750 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 in an ORDER BY
26760 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 or GROUP BY clau
26770 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a se.</dd>)^.**.**
26780 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
26790 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c EXPR_DEPTH]] ^(<
267a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
267b0 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a EXPR_DEPTH</dt>.
267c0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
267d0 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 um depth of the
267e0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e parse tree on an
267f0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 y expression.</d
26800 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
26810 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
26820 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 ND_SELECT]] ^(<d
26830 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 t>SQLITE_LIMIT_C
26840 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f OMPOUND_SELECT</
26850 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
26860 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
26870 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 terms in a comp
26880 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 ound SELECT stat
26890 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ement.</dd>)^.**
268a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
268b0 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c IT_VDBE_OP]] ^(<
268c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
268d0 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 VDBE_OP</dt>.**
268e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
268f0 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 number of instru
26900 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 ctions in a virt
26910 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 ual machine prog
26920 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 ram.** used to i
26930 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 mplement an SQL
26940 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 statement. This
26950 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 limit is not cu
26960 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 rrently.** enfor
26970 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 ced, though that
26980 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 might be added
26990 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 in some future r
269a0 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c elease of.** SQL
269b0 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ite.</dd>)^.**.*
269c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
269d0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 _FUNCTION_ARG]]
269e0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
269f0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c IT_FUNCTION_ARG<
26a00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
26a10 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
26a20 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 f arguments on a
26a30 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 function.</dd>)
26a40 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
26a50 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d _LIMIT_ATTACHED]
26a60 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
26a70 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 IMIT_ATTACHED</d
26a80 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
26a90 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
26aa0 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 [ATTACH | attach
26ab0 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e ed databases].)^
26ac0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
26ad0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f LITE_LIMIT_LIKE_
26ae0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d PATTERN_LENGTH]]
26af0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 .** ^(<dt>SQLITE
26b00 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 _LIMIT_LIKE_PATT
26b10 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a ERN_LENGTH</dt>.
26b20 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
26b30 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 um length of the
26b40 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e pattern argumen
26b50 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 t to the [LIKE]
26b60 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 or.** [GLOB] ope
26b70 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a rators.</dd>)^.*
26b80 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
26b90 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
26ba0 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 BER]].** ^(<dt>S
26bb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
26bc0 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e ABLE_NUMBER</dt>
26bd0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
26be0 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 mum index number
26bf0 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 of any [paramet
26c00 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 er] in an SQL st
26c10 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a atement.)^.**.**
26c20 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
26c30 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 TRIGGER_DEPTH]]
26c40 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
26c50 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 IT_TRIGGER_DEPTH
26c60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
26c70 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f maximum depth o
26c80 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 f recursion for
26c90 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e triggers.</dd>)^
26ca0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
26cb0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 LIMIT_WORKER_THR
26cc0 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c EADS]] ^(<dt>SQL
26cd0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 ITE_LIMIT_WORKER
26ce0 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a _THREADS</dt>.**
26cf0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
26d00 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c number of auxil
26d10 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 iary worker thre
26d20 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c ads that a singl
26d30 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
26d40 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 tatement] may st
26d50 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c art.</dd>)^.** <
26d60 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
26d70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e SQLITE_LIMIT_LEN
26d80 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 GTH
26d90 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
26da0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 SQLITE_LIMIT_SQ
26db0 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 L_LENGTH
26dc0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
26dd0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 e SQLITE_LIMIT_C
26de0 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 OLUMN
26df0 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 2.#defi
26e00 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
26e10 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 EXPR_DEPTH
26e20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 3.#def
26e30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
26e40 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 _COMPOUND_SELECT
26e50 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 4.#de
26e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
26e70 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 T_VDBE_OP
26e80 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 5.#d
26e90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
26ea0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 IT_FUNCTION_ARG
26eb0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 6.#
26ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
26ed0 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 MIT_ATTACHED
26ee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 7.
26ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
26f00 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 IMIT_LIKE_PATTER
26f10 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 N_LENGTH 8
26f20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
26f30 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
26f40 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 UMBER
26f50 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 9.#define SQLITE
26f60 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 _LIMIT_TRIGGER_D
26f70 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 EPTH
26f80 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 10.#define SQLIT
26f90 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 E_LIMIT_WORKER_T
26fa0 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 HREADS
26fb0 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 11../*.** CAPI3
26fc0 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 REF: Compiling A
26fd0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a n SQL Statement.
26fe0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 ** KEYWORDS: {SQ
26ff0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 L statement comp
27000 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a iler}.** METHOD:
27010 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 sqlite3.** CONS
27020 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 TRUCTOR: sqlite3
27030 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 _stmt.**.** To e
27040 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 xecute an SQL qu
27050 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 ery, it must fir
27060 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 st be compiled i
27070 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a nto a byte-code.
27080 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 ** program using
27090 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f one of these ro
270a0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 utines..**.** Th
270b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
270c0 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 , "db", is a [da
270d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
270e0 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d n] obtained from
270f0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 a.** prior succ
27100 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
27110 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
27120 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
27130 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 2()] or.** [sqli
27140 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 te3_open16()].
27150 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e The database con
27160 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 nection must not
27170 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 have been close
27180 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 d..**.** The sec
27190 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a ond argument, "z
271a0 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 Sql", is the sta
271b0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d tement to be com
271c0 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a piled, encoded.*
271d0 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d * as either UTF-
271e0 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 8 or UTF-16. Th
271f0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
27200 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
27210 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 prepare_v2().**
27220 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 interfaces use U
27230 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 TF-8, and sqlite
27240 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 3_prepare16() an
27250 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
27260 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 e16_v2().** use
27270 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 UTF-16..**.** ^I
27280 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 f the nByte argu
27290 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 ment is negative
272a0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 , then zSql is r
272b0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a ead up to the.**
272c0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d first zero term
272d0 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 inator. ^If nByt
272e0 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 e is positive, t
272f0 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a hen it is the.**
27300 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
27310 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e read from zSql.
27320 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a ^If nByte is z
27330 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 ero, then no pre
27340 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
27350 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e nt is generated.
27360 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 .** If the calle
27370 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 r knows that the
27380 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 supplied string
27390 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 is nul-terminat
273a0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 ed, then.** ther
273b0 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 e is a small per
273c0 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 formance advanta
273d0 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e ge to passing an
273e0 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 nByte parameter
273f0 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 that.** is the
27400 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
27410 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 in the input str
27420 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 ing <i>including
27430 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d </i>.** the nul-
27440 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a terminator..**.*
27450 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 * ^If pzTail is
27460 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 not NULL then *p
27470 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f zTail is made to
27480 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 point to the fi
27490 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 rst byte.** past
274a0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
274b0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d first SQL statem
274c0 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 ent in zSql. Th
274d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c ese routines onl
274e0 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 y.** compile the
274f0 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 first statement
27500 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a in zSql, so *pz
27510 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 Tail is left poi
27520 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 nting to.** what
27530 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 remains uncompi
27540 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 led..**.** ^*ppS
27550 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e tmt is left poin
27560 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c ting to a compil
27570 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ed [prepared sta
27580 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e tement] that can
27590 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 be.** executed
275a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 using [sqlite3_s
275b0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 tep()]. ^If the
275c0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 re is an error,
275d0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a *ppStmt is set.*
275e0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 * to NULL. ^If
275f0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 the input text c
27600 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 ontains no SQL (
27610 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 if the input is
27620 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 an empty.** stri
27630 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 ng or a comment)
27640 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 then *ppStmt is
27650 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a set to NULL..**
27660 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f The calling pro
27670 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e cedure is respon
27680 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 sible for deleti
27690 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a ng the compiled.
276a0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
276b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
276c0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 finalize()] afte
276d0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 r it has finishe
276e0 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 d with it..** pp
276f0 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 Stmt may not be
27700 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 NULL..**.** ^On
27710 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c success, the sql
27720 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 ite3_prepare() f
27730 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 amily of routine
27740 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 s return [SQLITE
27750 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 _OK];.** otherwi
27760 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 se an [error cod
27770 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a e] is returned..
27780 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
27790 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 3_prepare_v2() a
277a0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
277b0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 re16_v2() interf
277c0 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f aces are.** reco
277d0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 mmended for all
277e0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 new programs. Th
277f0 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 e two older inte
27800 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 rfaces are retai
27810 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 ned.** for backw
27820 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
27830 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 ty, but their us
27840 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 e is discouraged
27850 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 ..** ^In the "v2
27860 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 " interfaces, th
27870 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
27880 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 ment.** that is
27890 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 returned (the [s
278a0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a qlite3_stmt] obj
278b0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 ect) contains a
278c0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f copy of the.** o
278d0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 riginal SQL text
278e0 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 . This causes th
278f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
27900 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a )] interface to.
27910 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 ** behave differ
27920 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 ently in three w
27930 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a ays:.**.** <ol>.
27940 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 ** <li>.** ^If t
27950 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
27960 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 ma changes, inst
27970 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 ead of returning
27980 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
27990 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 as it.** always
279a0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 used to do, [sq
279b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
279c0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
279d0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 recompile the S
279e0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 QL.** statement
279f0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 and try to run i
27a00 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 t again. As many
27a10 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f as [SQLITE_MAX_
27a20 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a SCHEMA_RETRY].**
27a30 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 retries will oc
27a40 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 cur before sqlit
27a50 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 e3_step() gives
27a60 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 up and returns a
27a70 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 n error..** </li
27a80 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 >.**.** <li>.**
27a90 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f ^When an error o
27aa0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f ccurs, [sqlite3_
27ab0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 step()] will ret
27ac0 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 urn one of the d
27ad0 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f etailed.** [erro
27ae0 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 r codes] or [ext
27af0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
27b00 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 s]. ^The legacy
27b10 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 behavior was th
27b20 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 at.** [sqlite3_s
27b30 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c tep()] would onl
27b40 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 y return a gener
27b50 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ic [SQLITE_ERROR
27b60 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a ] result code.**
27b70 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 and the applica
27b80 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 tion would have
27b90 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 to make a second
27ba0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
27bb0 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 3_reset()].** in
27bc0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 order to find t
27bd0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 he underlying ca
27be0 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c use of the probl
27bf0 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 em. With the "v2
27c00 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 " prepare.** int
27c10 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 erfaces, the und
27c20 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 erlying reason f
27c30 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 or the error is
27c40 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
27c50 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a tely..** </li>.*
27c60 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 *.** <li>.** ^If
27c70 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 the specific va
27c80 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 lue bound to [pa
27c90 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 rameter | host p
27ca0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 arameter] in the
27cb0 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 .** WHERE claus
27cc0 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 e might influenc
27cd0 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 e the choice of
27ce0 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 query plan for a
27cf0 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 statement,.** t
27d00 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
27d10 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 t will be automa
27d20 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c tically recompil
27d30 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 ed, as if there
27d40 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 had been .** a s
27d50 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e chema change, on
27d60 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c the first [sql
27d70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c ite3_step()] cal
27d80 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 l following any
27d90 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 change.** to the
27da0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
27db0 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 ext | bindings]
27dc0 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 of that [paramet
27dd0 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 er]. .** ^The sp
27de0 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 ecific value of
27df0 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 WHERE-clause [pa
27e00 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 rameter] might i
27e10 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a nfluence the .**
27e20 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 choice of query
27e30 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 plan if the par
27e40 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 ameter is the le
27e50 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 ft-hand side of
27e60 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b a [LIKE].** or [
27e70 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f GLOB] operator o
27e80 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 r if the paramet
27e90 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 er is compared t
27ea0 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c o an indexed col
27eb0 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b umn.** and the [
27ec0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 SQLITE_ENABLE_ST
27ed0 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d AT3] compile-tim
27ee0 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 e option is enab
27ef0 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a led..** </li>.**
27f00 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 </ol>.*/.int sq
27f10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 lite3_prepare(.
27f20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
27f30 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
27f40 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
27f50 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
27f60 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
27f70 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 statement, UTF-8
27f80 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
27f90 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
27fa0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
27fb0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
27fc0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
27fd0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
27fe0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
27ff0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
28000 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
28010 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
28020 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
28030 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
28040 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
28050 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
28060 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
28070 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
28080 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
28090 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
280a0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
280b0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
280c0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
280d0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
280e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
280f0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
28100 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
28110 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
28120 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
28130 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
28140 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
28150 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
28160 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
28170 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
28180 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
28190 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
281a0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 repare16(. sqli
281b0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
281c0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
281d0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
281e0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
281f0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
28200 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
28210 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
28220 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
28230 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
28240 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
28250 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
28260 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
28270 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
28280 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
28290 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
282a0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
282b0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
282c0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
282d0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
282e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
282f0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
28300 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
28310 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
28320 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
28330 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
28340 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
28350 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
28360 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
28370 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
28380 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
28390 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
283a0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
283b0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
283c0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
283d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
283e0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
283f0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
28400 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
28410 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
28420 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
28430 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 F: Retrieving St
28440 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d atement SQL.** M
28450 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
28460 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 tmt.**.** ^This
28470 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
28480 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
28490 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f e a saved copy o
284a0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a f the original.*
284b0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 * SQL text used
284c0 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 to create a [pre
284d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
284e0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 if that stateme
284f0 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c nt was.** compil
28500 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ed using either
28510 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
28520 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
28530 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
28540 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 )]..*/.const cha
28550 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 r *sqlite3_sql(s
28560 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
28570 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
28580 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
28590 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d If An SQL Statem
285a0 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 ent Writes The D
285b0 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f atabase.** METHO
285c0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
285d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
285e0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
285f0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (X) interface re
28600 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d turns true (non-
28610 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 zero) if.** and
28620 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 only if the [pre
28630 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
28640 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 X makes no dire
28650 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a ct changes to.**
28660 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
28670 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
28680 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 e..**.** Note th
28690 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d at [application-
286a0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
286b0 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 tions] or.** [vi
286c0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 rtual tables] mi
286d0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 ght change the d
286e0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 atabase indirect
286f0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 ly as a side eff
28700 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 ect. .** ^(For
28710 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 example, if an a
28720 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
28730 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 es a function "e
28740 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 val()" that .**
28750 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 calls [sqlite3_e
28760 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 xec()], then the
28770 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 following SQL s
28780 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a tatement would.*
28790 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 * change the dat
287a0 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 abase file throu
287b0 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a gh side-effects:
287c0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
287d0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 te><pre>.** S
287e0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 ELECT eval('DELE
287f0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f TE FROM t1') FRO
28800 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c M t2;.** </pre><
28810 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
28820 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 ** But because t
28830 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 he [SELECT] stat
28840 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 ement does not c
28850 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
28860 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 se file.** direc
28870 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d tly, sqlite3_stm
28880 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 t_readonly() wou
28890 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 ld still return
288a0 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 true.)^.**.** ^T
288b0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 ransaction contr
288c0 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 ol statements su
288d0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b ch as [BEGIN], [
288e0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 COMMIT], [ROLLBA
288f0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 CK],.** [SAVEPOI
28900 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 NT], and [RELEAS
28910 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 E] cause sqlite3
28920 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
28930 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c to return true,
28940 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 .** since the st
28950 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c atements themsel
28960 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 ves do not actua
28970 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 lly modify the d
28980 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 atabase but.** r
28990 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 ather they contr
289a0 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 ol the timing of
289b0 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 when other stat
289c0 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 ements modify th
289d0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 e .** database.
289e0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 ^The [ATTACH] a
289f0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 nd [DETACH] stat
28a00 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 ements also caus
28a10 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d e.** sqlite3_stm
28a20 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 t_readonly() to
28a30 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 return true sinc
28a40 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 e, while those s
28a50 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 tatements.** cha
28a60 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 nge the configur
28a70 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 ation of a datab
28a80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 ase connection,
28a90 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 they do not make
28aa0 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 .** changes to
28ab0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
28ac0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
28ad0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e s on disk..*/.in
28ae0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 t sqlite3_stmt_r
28af0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f eadonly(sqlite3_
28b00 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
28b10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
28b20 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 etermine If A Pr
28b30 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
28b40 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a Has Been Reset.
28b50 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
28b60 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
28b70 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f he sqlite3_stmt_
28b80 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 busy(S) interfac
28b90 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 e returns true (
28ba0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 non-zero) if the
28bb0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
28bc0 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 atement] S has b
28bd0 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c een stepped at l
28be0 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 east once using
28bf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
28c00 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f p(S)] but has no
28c10 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 t run to complet
28c20 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e ion and/or has n
28c30 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 ot .** been rese
28c40 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
28c50 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 _reset(S)]. ^Th
28c60 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 e sqlite3_stmt_b
28c70 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 usy(S).** interf
28c80 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 ace returns fals
28c90 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c e if S is a NULL
28ca0 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 pointer. If S
28cb0 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c is not a .** NUL
28cc0 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 L pointer and is
28cd0 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 not a pointer t
28ce0 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 o a valid [prepa
28cf0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
28d00 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 * object, then t
28d10 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
28d20 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
28d30 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c bably undesirabl
28d40 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e e..**.** This in
28d50 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
28d60 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 sed in combinati
28d70 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 on [sqlite3_next
28d80 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c _stmt()].** to l
28d90 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 ocate all prepar
28da0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 ed statements as
28db0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 sociated with a
28dc0 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e database .** con
28dd0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 nection that are
28de0 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e in need of bein
28df0 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 g reset. This c
28e00 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 an be used,.** f
28e10 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 or example, in d
28e20 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e iagnostic routin
28e30 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 es to search for
28e40 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 prepared .** st
28e50 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 atements that ar
28e60 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e e holding a tran
28e70 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f saction open..*/
28e80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d .int sqlite3_stm
28e90 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 t_busy(sqlite3_s
28ea0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
28eb0 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 PI3REF: Dynamica
28ec0 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 lly Typed Value
28ed0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 Object.** KEYWOR
28ee0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 DS: {protected s
28ef0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 qlite3_value} {u
28f00 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
28f10 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 e3_value}.**.**
28f20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
28f30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
28f40 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e ject to represen
28f50 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 t all values.**
28f60 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 that can be stor
28f70 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 ed in a database
28f80 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 table. SQLite u
28f90 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 ses dynamic typi
28fa0 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 ng.** for the va
28fb0 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 lues it stores.
28fc0 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 ^Values stored
28fd0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 in sqlite3_value
28fe0 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 objects.** can
28ff0 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f be integers, flo
29000 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 ating point valu
29010 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f es, strings, BLO
29020 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a Bs, or NULL..**.
29030 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 ** An sqlite3_va
29040 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 lue object may b
29050 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 e either "protec
29060 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 ted" or "unprote
29070 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 cted"..** Some i
29080 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 nterfaces requir
29090 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 e a protected sq
290a0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 lite3_value. Ot
290b0 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a her interfaces.*
290c0 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 * will accept ei
290d0 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 ther a protected
290e0 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 or an unprotect
290f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
29100 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 ..** Every inter
29110 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 face that accept
29120 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 s sqlite3_value
29130 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 arguments specif
29140 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f ies.** whether o
29150 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 r not it require
29160 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 s a protected sq
29170 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 lite3_value. Th
29180 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 e.** [sqlite3_va
29190 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 lue_dup()] inter
291a0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 face can be used
291b0 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 to construct a
291c0 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 new .** protecte
291d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
291e0 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 from an unprotec
291f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
29200 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 e..**.** The ter
29210 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 ms "protected" a
29220 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 nd "unprotected"
29230 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 refer to whethe
29240 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 r or not.** a mu
29250 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e tex is held. An
29260 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 internal mutex
29270 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 is held for a pr
29280 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
29290 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
292a0 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 but no mutex is
292b0 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 held for an unpr
292c0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
292d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e e3_value object.
292e0 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 If SQLite is c
292f0 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 ompiled to be si
29300 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a ngle-threaded.**
29310 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 (with [SQLITE_T
29320 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 HREADSAFE=0] and
29330 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 with [sqlite3_t
29340 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 hreadsafe()] ret
29350 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 urning 0).** or
29360 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e if SQLite is run
29370 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 in one of reduc
29380 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a ed mutex modes .
29390 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
293a0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 G_SINGLETHREAD]
293b0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
293c0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a G_MULTITHREAD].*
293d0 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 * then there is
293e0 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 no distinction b
293f0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 etween protected
29400 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 and unprotected
29410 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
29420 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 e objects and th
29430 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 ey can be used i
29440 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 nterchangeably.
29450 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 However,.** for
29460 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f maximum code po
29470 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 rtability it is
29480 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 recommended that
29490 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
294a0 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 still make the
294b0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 distinction betw
294c0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e een protected an
294d0 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a d unprotected.**
294e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
294f0 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e bjects even when
29500 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 not strictly re
29510 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 quired..**.** ^T
29520 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
29530 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 objects that ar
29540 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 e passed as para
29550 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a meters into the.
29560 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
29570 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f n of [applicatio
29580 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
29590 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f nctions] are pro
295a0 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 tected..** ^The
295b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
295c0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 ject returned by
295d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
295e0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 umn_value()] is
295f0 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 unprotected..**
29600 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 Unprotected sqli
29610 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
29620 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 s may only be us
29630 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 ed with.** [sqli
29640 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
29650 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
29660 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a _bind_value()]..
29670 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
29680 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c value_blob | sql
29690 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 ite3_value_type(
296a0 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 )] family of.**
296b0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 interfaces requi
296c0 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c re protected sql
296d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
296e0 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 ts..*/.typedef s
296f0 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 truct Mem sqlite
29700 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 3_value;../*.**
29710 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 CAPI3REF: SQL Fu
29720 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f nction Context O
29730 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 bject.**.** The
29740 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 context in which
29750 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e an SQL function
29760 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f executes is sto
29770 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c red in an.** sql
29780 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a ite3_context obj
29790 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 ect. ^A pointer
297a0 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 to an sqlite3_c
297b0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a ontext object.**
297c0 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 is always first
297d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 parameter to [a
297e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
297f0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
29800 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 ]..** The applic
29810 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
29820 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 L function imple
29830 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 mentation will p
29840 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e ass this.** poin
29850 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f ter through into
29860 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
29870 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 e3_result_int |
29880 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 sqlite3_result()
29890 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 ],.** [sqlite3_a
298a0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
298b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 ()], [sqlite3_us
298c0 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b er_data()],.** [
298d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f sqlite3_context_
298e0 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 db_handle()], [s
298f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
29900 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 ta()],.** and/or
29910 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
29920 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 xdata()]..*/.typ
29930 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
29940 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 te3_context sqli
29950 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a te3_context;../*
29960 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 .** CAPI3REF: Bi
29970 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 nding Values To
29980 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
29990 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a nts.** KEYWORDS:
299a0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
299b0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 } {host paramete
299c0 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 rs} {host parame
299d0 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 ter name}.** KEY
299e0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 WORDS: {SQL para
299f0 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 meter} {SQL para
29a00 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 meters} {paramet
29a10 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d er binding}.** M
29a20 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
29a30 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 tmt.**.** ^(In t
29a40 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
29a50 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b text input to [
29a60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
29a70 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 v2()] and its va
29a80 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 riants,.** liter
29a90 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 als may be repla
29aa0 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 ced by a [parame
29ab0 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 ter] that matche
29ac0 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 s one of followi
29ad0 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a ng.** templates:
29ae0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
29af0 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 li> ?.** <li>
29b00 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 ?NNN.** <li> :V
29b10 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 VV.** <li> @VVV
29b20 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a .** <li> $VVV.*
29b30 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e * </ul>.**.** In
29b40 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 the templates a
29b50 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 bove, NNN repres
29b60 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 ents an integer
29b70 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 literal,.** and
29b80 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 VVV represents a
29b90 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 n alphanumeric i
29ba0 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 dentifier.)^ ^T
29bb0 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 he values of the
29bc0 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 se.** parameters
29bd0 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 (also called "h
29be0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
29bf0 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 mes" or "SQL par
29c00 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e ameters").** can
29c10 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 be set using th
29c20 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
29c30 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 () routines defi
29c40 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 ned here..**.**
29c50 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
29c60 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
29c70 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
29c80 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a ines is always.*
29c90 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 * a pointer to t
29ca0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
29cb0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 ] object returne
29cc0 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 d from.** [sqlit
29cd0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
29ce0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
29cf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 ..**.** ^The sec
29d00 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
29d10 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
29d20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 SQL parameter t
29d30 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 o be set..** ^Th
29d40 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 e leftmost SQL p
29d50 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 arameter has an
29d60 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 index of 1. ^Wh
29d70 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 en the same name
29d80 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 d.** SQL paramet
29d90 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 er is used more
29da0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e than once, secon
29db0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 d and subsequent
29dc0 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 .** occurrences
29dd0 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e have the same in
29de0 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 dex as the first
29df0 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 occurrence..**
29e00 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e ^The index for n
29e10 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 amed parameters
29e20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 can be looked up
29e30 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
29e40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
29e50 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 meter_index()] A
29e60 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 PI if desired.
29e70 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f ^The index.** fo
29e80 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 r "?NNN" paramet
29e90 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 ers is the value
29ea0 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 of NNN..** ^The
29eb0 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 NNN value must
29ec0 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 be between 1 and
29ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 the [sqlite3_li
29ee0 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 mit()].** parame
29ef0 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ter [SQLITE_LIMI
29f00 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
29f10 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 R] (default valu
29f20 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e e: 999)..**.** ^
29f30 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
29f40 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 nt is the value
29f50 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 to bind to the p
29f60 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 arameter..** ^If
29f70 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
29f80 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
29f90 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 bind_text() or s
29fa0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
29fb0 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 16().** or sqlit
29fc0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 e3_bind_blob() i
29fd0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
29fe0 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 then the fourth
29ff0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 parameter.** is
2a000 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 ignored and the
2a010 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 end result is t
2a020 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 he same as sqlit
2a030 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a e3_bind_null()..
2a040 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 **.** ^(In those
2a050 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 routines that h
2a060 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 ave a fourth arg
2a070 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 ument, its value
2a080 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 is the.** numbe
2a090 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
2a0a0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f e parameter. To
2a0b0 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 be clear: the v
2a0c0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
2a0d0 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 umber of <u>byte
2a0e0 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c s</u> in the val
2a0f0 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ue, not the numb
2a100 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
2a110 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .)^.** ^If the f
2a120 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
2a130 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f to sqlite3_bind_
2a140 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 text() or sqlite
2a150 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 3_bind_text16().
2a160 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 ** is negative,
2a170 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 then the length
2a180 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 of the string is
2a190 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
2a1a0 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 f bytes up to th
2a1b0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 e first zero ter
2a1c0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 minator..** If t
2a1d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
2a1e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
2a1f0 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 ind_blob() is ne
2a200 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 gative, then.**
2a210 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
2a220 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 undefined..** If
2a230 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 a non-negative
2a240 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
2a250 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 is provided to
2a260 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2a270 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 t().** or sqlite
2a280 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 3_bind_text16()
2a290 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f or sqlite3_bind_
2a2a0 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a text64() then.**
2a2b0 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 that parameter
2a2c0 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 must be the byte
2a2d0 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 offset.** where
2a2e0 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 the NUL termina
2a2f0 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 tor would occur
2a300 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 assuming the str
2a310 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 ing were NUL.**
2a320 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 terminated. If
2a330 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 any NUL characte
2a340 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 rs occur at byte
2a350 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 offsets less th
2a360 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 an .** the value
2a370 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 of the fourth p
2a380 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 arameter then th
2a390 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 e resulting stri
2a3a0 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a ng value will.**
2a3b0 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 contain embedde
2a3c0 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 d NULs. The res
2a3d0 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f ult of expressio
2a3e0 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 ns involving str
2a3f0 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 ings.** with emb
2a400 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e edded NULs is un
2a410 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e defined..**.** ^
2a420 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 The fifth argume
2a430 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 nt to the BLOB a
2a440 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e nd string bindin
2a450 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 g interfaces.**
2a460 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 is a destructor
2a470 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 used to dispose
2a480 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a of the BLOB or.*
2a490 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 * string after S
2a4a0 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 QLite has finish
2a4b0 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 ed with it. ^Th
2a4c0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 e destructor is
2a4d0 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 called.** to dis
2a4e0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 pose of the BLOB
2a4f0 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 or string even
2a500 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 if the call to b
2a510 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a ind API fails..*
2a520 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 * ^If the fifth
2a530 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 argument is.** t
2a540 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 he special value
2a550 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d [SQLITE_STATIC]
2a560 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 , then SQLite as
2a570 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a sumes that the.*
2a580 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
2a590 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 in static, unma
2a5a0 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 naged space and
2a5b0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
2a5c0 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 be freed..** ^I
2a5d0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 f the fifth argu
2a5e0 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c ment has the val
2a5f0 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 ue [SQLITE_TRANS
2a600 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 IENT], then.** S
2a610 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 QLite makes its
2a620 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 own private copy
2a630 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d of the data imm
2a640 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 ediately, before
2a650 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f .** the sqlite3_
2a660 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
2a670 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
2a680 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d ^The sixth argum
2a690 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ent to sqlite3_b
2a6a0 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 ind_text64() mus
2a6b0 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b t be one of.** [
2a6c0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 SQLITE_UTF8], [S
2a6d0 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 QLITE_UTF16], [S
2a6e0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 QLITE_UTF16BE],
2a6f0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 or [SQLITE_UTF16
2a700 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 LE].** to specif
2a710 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f y the encoding o
2a720 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 f the text in th
2a730 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
2a740 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 r. If.** the si
2a750 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 xth argument to
2a760 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2a770 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 t64() is not one
2a780 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 of the.** allow
2a790 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 ed values shown
2a7a0 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 above, or if the
2a7b0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 text encoding i
2a7c0 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 s different.** f
2a7d0 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 rom the encoding
2a7e0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
2a7f0 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 e sixth paramete
2a800 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 r, then the beha
2a810 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 vior.** is undef
2a820 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ined..**.** ^The
2a830 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 sqlite3_bind_ze
2a840 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 roblob() routine
2a850 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 binds a BLOB of
2a860 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a length N that.*
2a870 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 * is filled with
2a880 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 zeroes. ^A zer
2a890 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 oblob uses a fix
2a8a0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d ed amount of mem
2a8b0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 ory.** (just an
2a8c0 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 integer to hold
2a8d0 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 its size) while
2a8e0 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 it is being proc
2a8f0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c essed..** Zerobl
2a900 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 obs are intended
2a910 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 to serve as pla
2a920 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c ceholders for BL
2a930 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e OBs whose.** con
2a940 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 tent is later wr
2a950 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b itten using.** [
2a960 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
2a970 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 n | incremental
2a980 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e BLOB I/O] routin
2a990 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 es..** ^A negati
2a9a0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 ve value for the
2a9b0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 zeroblob result
2a9c0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 s in a zero-leng
2a9d0 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e th BLOB..**.** ^
2a9e0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 If any of the sq
2a9f0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
2aa00 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c outines are call
2aa10 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 ed with a NULL p
2aa20 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 ointer.** for th
2aa30 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2aa40 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 ement] or with a
2aa50 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2aa60 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a ent for which.**
2aa70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2aa80 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 ] has been calle
2aa90 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 d more recently
2aaa0 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 than [sqlite3_re
2aab0 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 set()],.** then
2aac0 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 the call will re
2aad0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 turn [SQLITE_MIS
2aae0 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 USE]. If any sq
2aaf0 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a lite3_bind_().**
2ab00 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 routine is pass
2ab10 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 ed a [prepared s
2ab20 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 tatement] that h
2ab30 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 as been finalize
2ab40 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 d, the.** result
2ab50 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e is undefined an
2ab60 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 d probably harmf
2ab70 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 ul..**.** ^Bindi
2ab80 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 ngs are not clea
2ab90 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 red by the [sqli
2aba0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 te3_reset()] rou
2abb0 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e tine..** ^Unboun
2abc0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 d parameters are
2abd0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
2abe0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 NULL..**.** ^The
2abf0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 sqlite3_bind_*
2ac00 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
2ac10 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 [SQLITE_OK] on s
2ac20 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 uccess or an.**
2ac30 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 [error code] if
2ac40 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 anything goes wr
2ac50 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 ong..** ^[SQLITE
2ac60 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 _TOOBIG] might b
2ac70 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 e returned if th
2ac80 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 e size of a stri
2ac90 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 ng or BLOB.** ex
2aca0 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 ceeds limits imp
2acb0 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 osed by [sqlite3
2acc0 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f _limit]([SQLITE_
2acd0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f LIMIT_LENGTH]) o
2ace0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 r.** [SQLITE_MAX
2acf0 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 _LENGTH]..** ^[S
2ad00 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 QLITE_RANGE] is
2ad10 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 returned if the
2ad20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 parameter.** ind
2ad30 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e ex is out of ran
2ad40 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f ge. ^[SQLITE_NO
2ad50 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 MEM] is returned
2ad60 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 if malloc() fai
2ad70 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ls..**.** See al
2ad80 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
2ad90 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
2ada0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 t()],.** [sqlite
2adb0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2adc0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 _name()], and [s
2add0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2ade0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
2adf0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
2ae00 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 ind_blob(sqlite3
2ae10 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
2ae20 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c st void*, int n,
2ae30 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
2ae40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
2ae50 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 nd_blob64(sqlite
2ae60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
2ae70 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 nst void*, sqlit
2ae80 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 e3_uint64,.
2ae90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2aea0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a void(*)(void*
2aeb0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f ));.int sqlite3_
2aec0 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 bind_double(sqli
2aed0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2aee0 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c double);.int sql
2aef0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 ite3_bind_int(sq
2af00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2af10 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 , int);.int sqli
2af20 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 te3_bind_int64(s
2af30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2af40 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 t, sqlite3_int64
2af50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
2af60 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 ind_null(sqlite3
2af70 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e _stmt*, int);.in
2af80 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 t sqlite3_bind_t
2af90 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ext(sqlite3_stmt
2afa0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 *,int,const char
2afb0 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f *,int,void(*)(vo
2afc0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 id*));.int sqlit
2afd0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 e3_bind_text16(s
2afe0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2aff0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 t, const void*,
2b000 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 int, void(*)(voi
2b010 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 d*));.int sqlite
2b020 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 3_bind_text64(sq
2b030 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2b040 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 , const char*, s
2b050 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 qlite3_uint64,.
2b060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2b070 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 void(*)(
2b080 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 void*), unsigned
2b090 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b char encoding);
2b0a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
2b0b0 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f d_value(sqlite3_
2b0c0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
2b0d0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t sqlite3_value*
2b0e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
2b0f0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c ind_zeroblob(sql
2b100 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
2b110 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 int n);../*.**
2b120 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
2b130 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 Of SQL Paramete
2b140 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 rs.** METHOD: sq
2b150 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2b160 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 ^This routine c
2b170 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 an be used to fi
2b180 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 nd the number of
2b190 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 [SQL parameters
2b1a0 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 ].** in a [prepa
2b1b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
2b1c0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 SQL parameters
2b1d0 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 are tokens of th
2b1e0 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 e.** form "?", "
2b1f0 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 ?NNN", ":AAA", "
2b200 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 $AAA", or "@AAA"
2b210 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a that serve as.*
2b220 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 * placeholders f
2b230 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 or values that a
2b240 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 re [sqlite3_bind
2b250 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a _blob | bound].*
2b260 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 * to the paramet
2b270 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 ers at a later t
2b280 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 ime..**.** ^(Thi
2b290 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c s routine actual
2b2a0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 ly returns the i
2b2b0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 ndex of the larg
2b2c0 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a est (rightmost).
2b2d0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f ** parameter. Fo
2b2e0 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 r all forms exce
2b2f0 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 pt ?NNN, this wi
2b300 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f ll correspond to
2b310 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
2b320 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 f unique paramet
2b330 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 ers. If paramet
2b340 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 ers of the ?NNN
2b350 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a form are used,.*
2b360 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 * there may be g
2b370 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e aps in the list.
2b380 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 )^.**.** See als
2b390 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
2b3a0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
2b3b0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
2b3c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2b3d0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a r_name()], and.*
2b3e0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2b3f0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
2b400 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 )]..*/.int sqlit
2b410 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2b420 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f r_count(sqlite3_
2b430 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
2b440 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 API3REF: Name Of
2b450 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 A Host Paramete
2b460 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c r.** METHOD: sql
2b470 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2b480 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
2b490 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
2b4a0 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 (P,N) interface
2b4b0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
2b4c0 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 ame of the N-th
2b4d0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 [SQL parameter]
2b4e0 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 in the [prepared
2b4f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a statement] P..*
2b500 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 * ^(SQL paramete
2b510 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 rs of the form "
2b520 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 ?NNN" or ":AAA"
2b530 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 or "@AAA" or "$A
2b540 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 AA".** have a na
2b550 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 me which is the
2b560 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 string "?NNN" or
2b570 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 ":AAA" or "@AAA
2b580 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 " or "$AAA".** r
2b590 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
2b5a0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
2b5b0 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 the initial ":"
2b5c0 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 or "$" or "@" or
2b5d0 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 "?".** is inclu
2b5e0 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 ded as part of t
2b5f0 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 he name.)^.** ^P
2b600 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
2b610 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 form "?" withou
2b620 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e t a following in
2b630 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 teger have no na
2b640 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 me.** and are re
2b650 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 ferred to as "na
2b660 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e meless" or "anon
2b670 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 ymous parameters
2b680 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 "..**.** ^The fi
2b690 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 rst host paramet
2b6a0 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 er has an index
2b6b0 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a of 1, not 0..**.
2b6c0 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 ** ^If the value
2b6d0 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e N is out of ran
2b6e0 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 ge or if the N-t
2b6f0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
2b700 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e * nameless, then
2b710 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 NULL is returne
2b720 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 d. ^The returne
2b730 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 d string is.** a
2b740 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 lways in UTF-8 e
2b750 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 ncoding even if
2b760 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 the named parame
2b770 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 ter was.** origi
2b780 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 nally specified
2b790 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 as UTF-16 in [sq
2b7a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
2b7b0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
2b7c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
2b7d0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 ]..**.** See als
2b7e0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
2b7f0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
2b800 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
2b810 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2b820 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a r_count()], and.
2b830 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
2b840 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
2b850 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ()]..*/.const ch
2b860 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 ar *sqlite3_bind
2b870 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
2b880 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2b890 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
2b8a0 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 3REF: Index Of A
2b8b0 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 Parameter With
2b8c0 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 A Given Name.**
2b8d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
2b8e0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 stmt.**.** ^Retu
2b8f0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 rn the index of
2b900 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 an SQL parameter
2b910 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e given its name.
2b920 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 ^The.** index
2b930 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 value returned i
2b940 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 s suitable for u
2b950 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 se as the second
2b960 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f .** parameter to
2b970 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2b980 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
2b990 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a ()]. ^A zero.**
2b9a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
2b9b0 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 no matching para
2b9c0 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 meter is found.
2b9d0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a ^The parameter.
2b9e0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 ** name must be
2b9f0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 given in UTF-8 e
2ba00 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 ven if the origi
2ba10 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a nal statement.**
2ba20 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 was prepared fr
2ba30 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 om UTF-16 text u
2ba40 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
2ba50 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a epare16_v2()]..*
2ba60 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2ba70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2ba80 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
2ba90 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
2baa0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
2bab0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b unt()], and.** [
2bac0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2bad0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
2bae0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2baf0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
2bb00 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d ndex(sqlite3_stm
2bb10 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a t*, const char *
2bb20 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 zName);../*.** C
2bb30 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 API3REF: Reset A
2bb40 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 ll Bindings On A
2bb50 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
2bb60 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ent.** METHOD: s
2bb70 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2bb80 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 * ^Contrary to t
2bb90 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 he intuition of
2bba0 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 many, [sqlite3_r
2bbb0 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 eset()] does not
2bbc0 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 reset.** the [s
2bbd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2bbe0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 | bindings] on
2bbf0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2bc00 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 ement]..** ^Use
2bc10 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 this routine to
2bc20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 reset all host p
2bc30 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c arameters to NUL
2bc40 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 L..*/.int sqlite
2bc50 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 3_clear_bindings
2bc60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
2bc70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2bc80 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 : Number Of Colu
2bc90 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 mns In A Result
2bca0 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 Set.** METHOD: s
2bcb0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2bcc0 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 * ^Return the nu
2bcd0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
2bce0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 in the result se
2bcf0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 t returned by th
2bd00 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
2bd10 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 tatement]. ^This
2bd20 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2bd30 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 0 if pStmt is a
2bd40 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 n SQL.** stateme
2bd50 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 nt that does not
2bd60 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f return data (fo
2bd70 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 r example an [UP
2bd80 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 DATE])..**.** Se
2bd90 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
2bda0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a _data_count()].*
2bdb0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f /.int sqlite3_co
2bdc0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 lumn_count(sqlit
2bdd0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
2bde0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2bdf0 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 : Column Names I
2be00 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a n A Result Set.*
2be10 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
2be20 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
2be30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
2be40 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 urn the name ass
2be50 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 igned to a parti
2be60 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 cular column.**
2be70 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 in the result se
2be80 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 t of a [SELECT]
2be90 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 statement. ^The
2bea0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2beb0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 name().** interf
2bec0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
2bed0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d inter to a zero-
2bee0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
2bef0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 string.** and s
2bf00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
2bf10 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 me16() returns a
2bf20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 pointer to a ze
2bf30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
2bf40 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 UTF-16 string.
2bf50 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^The first para
2bf60 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 meter is the [pr
2bf70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2bf80 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d ].** that implem
2bf90 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 ents the [SELECT
2bfa0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 ] statement. ^Th
2bfb0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
2bfc0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c er is the.** col
2bfd0 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 umn number. ^Th
2bfe0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d e leftmost colum
2bff0 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a n is number 0..*
2c000 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e *.** ^The return
2c010 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 ed string pointe
2c020 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c r is valid until
2c030 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 either the [pre
2c040 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2c050 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 .** is destroyed
2c060 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e by [sqlite3_fin
2c070 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 alize()] or unti
2c080 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 l the statement
2c090 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 is automatically
2c0a0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 .** reprepared b
2c0b0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c y the first call
2c0c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
2c0d0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 p()] for a parti
2c0e0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 cular run.** or
2c0f0 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 until the next c
2c100 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 all to.** sqlite
2c110 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 3_column_name()
2c120 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
2c130 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 n_name16() on th
2c140 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a e same column..*
2c150 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 *.** ^If sqlite3
2c160 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 _malloc() fails
2c170 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 during the proce
2c180 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 ssing of either
2c190 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 routine.** (for
2c1a0 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 example during a
2c1b0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d conversion from
2c1c0 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 UTF-8 to UTF-16
2c1d0 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c ) then a.** NULL
2c1e0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 pointer is retu
2c1f0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 rned..**.** ^The
2c200 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c name of a resul
2c210 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 t column is the
2c220 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 value of the "AS
2c230 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 " clause for.**
2c240 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 that column, if
2c250 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 there is an AS c
2c260 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 lause. If there
2c270 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 is no AS clause
2c280 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d .** then the nam
2c290 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 e of the column
2c2a0 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 is unspecified a
2c2b0 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 nd may change fr
2c2c0 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 om.** one releas
2c2d0 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 e of SQLite to t
2c2e0 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 he next..*/.cons
2c2f0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
2c300 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 column_name(sqli
2c310 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
2c320 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
2c330 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
2c340 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
2c350 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a t*, int N);../*.
2c360 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 ** CAPI3REF: Sou
2c370 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 rce Of Data In A
2c380 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a Query Result.**
2c390 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2c3a0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _stmt.**.** ^The
2c3b0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 se routines prov
2c3c0 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 ide a means to d
2c3d0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 etermine the dat
2c3e0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e abase, table, an
2c3f0 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d d.** table colum
2c400 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 n that is the or
2c410 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 igin of a partic
2c420 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 ular result colu
2c430 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 mn in.** [SELECT
2c440 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 ] statement..**
2c450 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 ^The name of the
2c460 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 database or tab
2c470 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e le or column can
2c480 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a be returned as.
2c490 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d ** either a UTF-
2c4a0 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 8 or UTF-16 stri
2c4b0 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 ng. ^The _datab
2c4c0 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 ase_ routines re
2c4d0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 turn.** the data
2c4e0 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f base name, the _
2c4f0 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 table_ routines
2c500 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 return the table
2c510 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 name, and.** th
2c520 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e e origin_ routin
2c530 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f es return the co
2c540 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 lumn name..** ^T
2c550 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
2c560 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 ng is valid unti
2c570 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 l the [prepared
2c580 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 statement] is de
2c590 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 stroyed.** using
2c5a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2c5b0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 ze()] or until t
2c5c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
2c5d0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a automatically.**
2c5e0 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 reprepared by t
2c5f0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f he first call to
2c600 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2c610 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c ] for a particul
2c620 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 ar run.** or unt
2c630 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f il the same info
2c640 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 rmation is reque
2c650 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e sted.** again in
2c660 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 a different enc
2c670 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 oding..**.** ^Th
2c680 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 e names returned
2c690 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 are the origina
2c6a0 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d l un-aliased nam
2c6b0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 es of the.** dat
2c6c0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e abase, table, an
2c6d0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 d column..**.**
2c6e0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
2c6f0 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 ent to these int
2c700 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 erfaces is a [pr
2c710 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2c720 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e ]..** ^These fun
2c730 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e ctions return in
2c740 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
2c750 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 the Nth result c
2c760 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 olumn returned b
2c770 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 y.** the stateme
2c780 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 nt, where N is t
2c790 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 he second functi
2c7a0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 on argument..**
2c7b0 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 ^The left-most c
2c7c0 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 olumn is column
2c7d0 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 0 for these rout
2c7e0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ines..**.** ^If
2c7f0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 the Nth column r
2c800 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 eturned by the s
2c810 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 tatement is an e
2c820 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 xpression or.**
2c830 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 subquery and is
2c840 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c not a column val
2c850 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 ue, then all of
2c860 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 these functions
2c870 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 return.** NULL.
2c880 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 ^These routine
2c890 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 might also retur
2c8a0 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f n NULL if a memo
2c8b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
2c8c0 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 ror.** occurs.
2c8d0 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 ^Otherwise, they
2c8e0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 return the name
2c8f0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 of the attached
2c900 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
2c910 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 ,.** or column t
2c920 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 hat query result
2c930 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 column was extr
2c940 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a acted from..**.*
2c950 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f * ^As with all o
2c960 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 ther SQLite APIs
2c970 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 , those whose na
2c980 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 mes end with "16
2c990 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d " return.** UTF-
2c9a0 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 16 encoded strin
2c9b0 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 gs and the other
2c9c0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
2c9d0 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e n UTF-8..**.** ^
2c9e0 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f These APIs are o
2c9f0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
2ca00 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 the library was
2ca10 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
2ca20 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e he.** [SQLITE_EN
2ca30 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 ABLE_COLUMN_META
2ca40 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 DATA] C-preproce
2ca50 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a ssor symbol..**.
2ca60 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 ** If two or mor
2ca70 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f e threads call o
2ca80 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 ne or more of th
2ca90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 ese routines aga
2caa0 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a inst the same.**
2cab0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2cac0 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 ent and column a
2cad0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 t the same time
2cae0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 then the results
2caf0 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 are.** undefine
2cb00 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 d..**.** If two
2cb10 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 or more threads
2cb20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 call one or more
2cb30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
2cb40 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d umn_database_nam
2cb50 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 e | column metad
2cb60 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a ata interfaces].
2cb70 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ** for the same
2cb80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2cb90 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 ent] and result
2cba0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 column.** at the
2cbb0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 same time then
2cbc0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
2cbd0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f undefined..*/.co
2cbe0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
2cbf0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
2cc00 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 e_name(sqlite3_s
2cc10 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 tmt*,int);.const
2cc20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
2cc30 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e olumn_database_n
2cc40 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
2cc50 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
2cc60 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
2cc70 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 lumn_table_name(
2cc80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2cc90 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a t);.const void *
2cca0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2ccb0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 able_name16(sqli
2ccc0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
2ccd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
2cce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 te3_column_origi
2ccf0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 n_name(sqlite3_s
2cd00 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 tmt*,int);.const
2cd10 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
2cd20 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d olumn_origin_nam
2cd30 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
2cd40 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 *,int);../*.** C
2cd50 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 API3REF: Declare
2cd60 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 d Datatype Of A
2cd70 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 Query Result.**
2cd80 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
2cd90 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 stmt.**.** ^(The
2cda0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
2cdb0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 is a [prepared
2cdc0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 statement]..** I
2cdd0 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 f this statement
2cde0 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 is a [SELECT] s
2cdf0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 tatement and the
2ce00 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 Nth column of t
2ce10 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 he.** returned r
2ce20 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 esult set of tha
2ce30 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 t [SELECT] is a
2ce40 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f table column (no
2ce50 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 t an.** expressi
2ce60 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 on or subquery)
2ce70 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 then the declare
2ce80 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 d type of the ta
2ce90 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 ble.** column is
2cea0 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 returned.)^ ^I
2ceb0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e f the Nth column
2cec0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
2ced0 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 et is an.** expr
2cee0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
2cef0 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 ry, then a NULL
2cf00 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 pointer is retur
2cf10 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 ned..** ^The ret
2cf20 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 urned string is
2cf30 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 always UTF-8 enc
2cf40 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f oded..**.** ^(Fo
2cf50 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e r example, given
2cf60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 the database sc
2cf70 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 hema:.**.** CREA
2cf80 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 TE TABLE t1(c1 V
2cf90 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 ARIANT);.**.** a
2cfa0 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 nd the following
2cfb0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
2cfc0 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a compiled:.**.**
2cfd0 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 SELECT c1 + 1,
2cfe0 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a c1 FROM t1;.**.*
2cff0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 * this routine w
2d000 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 ould return the
2d010 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 string "VARIANT"
2d020 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 for the second
2d030 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e result.** column
2d040 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e (i==1), and a N
2d050 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 ULL pointer for
2d060 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 the first result
2d070 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 column (i==0).)
2d080 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ^.**.** ^SQLite
2d090 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e uses dynamic run
2d0a0 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e -time typing. ^
2d0b0 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 So just because
2d0c0 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 a column.** is d
2d0d0 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 eclared to conta
2d0e0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 in a particular
2d0f0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 type does not me
2d100 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 an that the.** d
2d110 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 ata stored in th
2d120 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 at column is of
2d130 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 the declared typ
2d140 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a e. SQLite is.**
2d150 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c strongly typed,
2d160 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 but the typing
2d170 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 is dynamic not s
2d180 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a tatic. ^Type.**
2d190 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 is associated w
2d1a0 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 ith individual v
2d1b0 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 alues, not with
2d1c0 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a the containers.*
2d1d0 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 * used to hold t
2d1e0 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a hose values..*/.
2d1f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
2d200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 te3_column_declt
2d210 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ype(sqlite3_stmt
2d220 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f *,int);.const vo
2d230 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
2d240 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 mn_decltype16(sq
2d250 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2d260 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2d270 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 F: Evaluate An S
2d280 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 QL Statement.**
2d290 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
2d2a0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 stmt.**.** After
2d2b0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2d2c0 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e tement] has been
2d2d0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 prepared using
2d2e0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 either.** [sqlit
2d2f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2d300 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
2d310 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
2d320 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 one of the legac
2d330 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 y.** interfaces
2d340 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2d350 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2d360 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 prepare16()], th
2d370 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d is function.** m
2d380 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e ust be called on
2d390 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 e or more times
2d3a0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 to evaluate the
2d3b0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a statement..**.**
2d3c0 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 The details of
2d3d0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
2d3e0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 the sqlite3_step
2d3f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 () interface dep
2d400 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 end.** on whethe
2d410 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 r the statement
2d420 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 was prepared usi
2d430 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 ng the newer "v2
2d440 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b " interface.** [
2d450 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2d460 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
2d470 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
2d480 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 )] or the older
2d490 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 legacy.** interf
2d4a0 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ace [sqlite3_pre
2d4b0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c pare()] and [sql
2d4c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
2d4d0 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 ]. The use of t
2d4e0 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 he.** new "v2" i
2d4f0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f nterface is reco
2d500 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 mmended for new
2d510 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 applications but
2d520 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
2d530 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f nterface will co
2d540 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 ntinue to be sup
2d550 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 ported..**.** ^I
2d560 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 n the legacy int
2d570 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 erface, the retu
2d580 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 rn value will be
2d590 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
2d5a0 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 BUSY],.** [SQLIT
2d5b0 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 E_DONE], [SQLITE
2d5c0 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 _ROW], [SQLITE_E
2d5d0 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 RROR], or [SQLIT
2d5e0 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 E_MISUSE]..** ^W
2d5f0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 ith the "v2" int
2d600 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 erface, any of t
2d610 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 he other [result
2d620 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 codes] or.** [e
2d630 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
2d640 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 odes] might be r
2d650 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e eturned as well.
2d660 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f .**.** ^[SQLITE_
2d670 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 BUSY] means that
2d680 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e the database en
2d690 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 gine was unable
2d6a0 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a to acquire the.*
2d6b0 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 * database locks
2d6c0 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 it needs to do
2d6d0 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 its job. ^If th
2d6e0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
2d6f0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 [COMMIT].** or
2d700 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f occurs outside o
2d710 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 f an explicit tr
2d720 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 ansaction, then
2d730 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 you can retry th
2d740 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 e.** statement.
2d750 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e If the statemen
2d760 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d t is not a [COMM
2d770 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 IT] and occurs w
2d780 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c ithin an.** expl
2d790 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e icit transaction
2d7a0 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 then you should
2d7b0 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 rollback the tr
2d7c0 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 ansaction before
2d7d0 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a .** continuing..
2d7e0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 **.** ^[SQLITE_D
2d7f0 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 ONE] means that
2d800 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 the statement ha
2d810 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 s finished execu
2d820 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 ting.** successf
2d830 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 ully. sqlite3_s
2d840 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 tep() should not
2d850 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e be called again
2d860 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c on this virtual
2d870 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 .** machine with
2d880 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e out first callin
2d890 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
2d8a0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 ()] to reset the
2d8b0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 virtual.** mach
2d8c0 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 ine back to its
2d8d0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a initial state..*
2d8e0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c *.** ^If the SQL
2d8f0 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 statement being
2d900 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e executed return
2d910 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e s any data, then
2d920 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a [SQLITE_ROW].**
2d930 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 is returned eac
2d940 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 h time a new row
2d950 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 of data is read
2d960 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 y for processing
2d970 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 by the.** calle
2d980 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 r. The values ma
2d990 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 y be accessed us
2d9a0 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 ing the [column
2d9b0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 access functions
2d9c0 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 ]..** sqlite3_st
2d9d0 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 ep() is called a
2d9e0 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 gain to retrieve
2d9f0 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 the next row of
2da00 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 data..**.** ^[S
2da10 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 QLITE_ERROR] mea
2da20 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 ns that a run-ti
2da30 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 me error (such a
2da40 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a s a constraint.*
2da50 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 * violation) has
2da60 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 occurred. sqli
2da70 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c te3_step() shoul
2da80 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 d not be called
2da90 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 again on.** the
2daa0 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 VM. More informa
2dab0 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e tion may be foun
2dac0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 d by calling [sq
2dad0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e lite3_errmsg()].
2dae0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 .** ^With the le
2daf0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
2db00 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 a more specific
2db10 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 error code (for
2db20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c example,.** [SQL
2db30 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 ITE_INTERRUPT],
2db40 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c [SQLITE_SCHEMA],
2db50 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 [SQLITE_CORRUPT
2db60 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 ], and so forth)
2db70 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 .** can be obtai
2db80 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b ned by calling [
2db90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2dba0 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 on the.** [prep
2dbb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
2dbc0 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 ^In the "v2" i
2dbd0 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 nterface,.** the
2dbe0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 more specific e
2dbf0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 rror code is ret
2dc00 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 urned directly b
2dc10 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 y sqlite3_step()
2dc20 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ..**.** [SQLITE_
2dc30 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 MISUSE] means th
2dc40 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 at the this rout
2dc50 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 ine was called i
2dc60 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a nappropriately..
2dc70 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 ** Perhaps it wa
2dc80 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 s called on a [p
2dc90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2dca0 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 t] that has.** a
2dcb0 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c lready been [sql
2dcc0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 ite3_finalize |
2dcd0 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e finalized] or on
2dce0 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a one that had.**
2dcf0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 previously retu
2dd00 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 rned [SQLITE_ERR
2dd10 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 OR] or [SQLITE_D
2dd20 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 ONE]. Or it cou
2dd30 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 ld.** be the cas
2dd40 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 e that the same
2dd50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2dd60 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 ion is being use
2dd70 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d d by two or.** m
2dd80 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 ore threads at t
2dd90 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 he same moment i
2dda0 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f n time..**.** Fo
2ddb0 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f r all versions o
2ddc0 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 f SQLite up to a
2ddd0 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 nd including 3.6
2dde0 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f .23.1, a call to
2ddf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
2de00 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 et()] was requir
2de10 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 ed after sqlite3
2de20 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 _step() returned
2de30 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 anything.** oth
2de40 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
2de50 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 ROW] before any
2de60 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 subsequent invoc
2de70 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 ation of.** sqli
2de80 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 te3_step(). Fai
2de90 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 lure to reset th
2dea0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
2deb0 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b ment using .** [
2dec0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2ded0 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e would result in
2dee0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 an [SQLITE_MISU
2def0 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a SE] return from.
2df00 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
2df10 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 ). But after ve
2df20 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 rsion 3.6.23.1,
2df30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 sqlite3_step() b
2df40 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 egan.** calling
2df50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2df60 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 ] automatically
2df70 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 in this circumst
2df80 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 ance rather.** t
2df90 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 han returning [S
2dfa0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
2dfb0 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 This is not cons
2dfc0 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 idered a compati
2dfd0 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 bility.** break
2dfe0 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c because any appl
2dff0 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 ication that eve
2e000 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 r receives an SQ
2e010 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f LITE_MISUSE erro
2e020 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 r.** is broken b
2e030 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 y definition. T
2e040 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f he [SQLITE_OMIT_
2e050 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 AUTORESET] compi
2e060 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a le-time option.*
2e070 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f * can be used to
2e080 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 restore the leg
2e090 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a acy behavior..**
2e0a0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 .** <b>Goofy Int
2e0b0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 erface Alert:</b
2e0c0 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 > In the legacy
2e0d0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 interface, the s
2e0e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a qlite3_step().**
2e0f0 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 API always retu
2e100 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 rns a generic er
2e110 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 ror code, [SQLIT
2e120 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 E_ERROR], follow
2e130 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 ing any.** error
2e140 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
2e150 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 ITE_BUSY] and [S
2e160 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
2e170 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a You must call.**
2e180 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2e190 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
2e1a0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 inalize()] in or
2e1b0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 der to find one
2e1c0 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 of the.** specif
2e1d0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ic [error codes]
2e1e0 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 that better des
2e1f0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 cribes the error
2e200 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 ..** We admit th
2e210 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f at this is a goo
2e220 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 fy design. The
2e230 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e problem has been
2e240 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 fixed.** with t
2e250 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
2e260 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 e. If you prepa
2e270 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 re all of your S
2e280 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
2e290 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
2e2a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2e2b0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
2e2c0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
2e2d0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 instead.** of t
2e2e0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 he legacy [sqlit
2e2f0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e e3_prepare()] an
2e300 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
2e310 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 re16()] interfac
2e320 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 es,.** then the
2e330 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 more specific [e
2e340 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 rror codes] are
2e350 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c returned directl
2e360 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f y.** by sqlite3_
2e370 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 step(). The use
2e380 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 of the "v2" int
2e390 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
2e3a0 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ended..*/.int sq
2e3b0 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 lite3_step(sqlit
2e3c0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
2e3d0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
2e3e0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
2e3f0 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a a result set.**
2e400 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2e410 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _stmt.**.** ^The
2e420 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
2e430 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 unt(P) interface
2e440 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
2e450 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
2e460 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 n the.** current
2e470 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 row of the resu
2e480 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 lt set of [prepa
2e490 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 red statement] P
2e4a0 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 ..** ^If prepare
2e4b0 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f d statement P do
2e4c0 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 es not have resu
2e4d0 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 lts ready to ret
2e4e0 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c urn.** (via call
2e4f0 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 s to the [sqlite
2e500 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 3_column_int | s
2e510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 qlite3_column_*(
2e520 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 )] of.** interfa
2e530 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 ces) then sqlite
2e540 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 3_data_count(P)
2e550 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 returns 0..** ^T
2e560 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
2e570 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 count(P) routine
2e580 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 also returns 0
2e590 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 if P is a NULL p
2e5a0 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 ointer..** ^The
2e5b0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
2e5c0 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 nt(P) routine re
2e5d0 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 turns 0 if the p
2e5e0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a revious call to.
2e5f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
2e600 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 ](P) returned [S
2e610 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 QLITE_DONE]. ^T
2e620 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
2e630 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c count(P).** will
2e640 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f return non-zero
2e650 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c if previous cal
2e660 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
2e670 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a ep](P) returned.
2e680 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c ** [SQLITE_ROW],
2e690 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 except in the c
2e6a0 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 ase of the [PRAG
2e6b0 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 MA incremental_v
2e6c0 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 acuum].** where
2e6d0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e it always return
2e6e0 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 s zero since eac
2e6f0 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d h step of that m
2e700 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 ulti-step.** pra
2e710 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f gma returns 0 co
2e720 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a lumns of data..*
2e730 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2e740 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
2e750 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 ount()].*/.int s
2e760 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2e770 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
2e780 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
2e790 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 API3REF: Fundame
2e7a0 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a ntal Datatypes.*
2e7b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 * KEYWORDS: SQLI
2e7c0 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 TE_TEXT.**.** ^(
2e7d0 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 Every value in S
2e7e0 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 QLite has one of
2e7f0 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 five fundamenta
2e800 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a l datatypes:.**.
2e810 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
2e820 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
2e830 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 teger.** <li> 64
2e840 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 -bit IEEE floati
2e850 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a ng point number.
2e860 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a ** <li> string.*
2e870 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c * <li> BLOB.** <
2e880 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c li> NULL.** </ul
2e890 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 >)^.**.** These
2e8a0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f constants are co
2e8b0 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 des for each of
2e8c0 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a those types..**.
2e8d0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 ** Note that the
2e8e0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e SQLITE_TEXT con
2e8f0 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 stant was also u
2e900 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 sed in SQLite ve
2e910 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 rsion 2.** for a
2e920 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 completely diff
2e930 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 erent meaning.
2e940 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 Software that li
2e950 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 nks against both
2e960 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 .** SQLite versi
2e970 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 on 2 and SQLite
2e980 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 version 3 should
2e990 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 use SQLITE3_TEX
2e9a0 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 T, not.** SQLITE
2e9b0 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e _TEXT..*/.#defin
2e9c0 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 e SQLITE_INTEGER
2e9d0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
2e9e0 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 TE_FLOAT 2.#d
2e9f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f efine SQLITE_BLO
2ea00 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 B 4.#define
2ea10 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 SQLITE_NULL
2ea20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 5.#ifdef SQLITE_
2ea30 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c TEXT.# undef SQL
2ea40 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 ITE_TEXT.#else.#
2ea50 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 define SQLITE_T
2ea60 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 EXT 3.#endif
2ea70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 .#define SQLITE3
2ea80 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a _TEXT 3../*.
2ea90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
2eaa0 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 ult Values From
2eab0 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f A Query.** KEYWO
2eac0 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 RDS: {column acc
2ead0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a ess functions}.*
2eae0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
2eaf0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
2eb00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
2eb10 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 urn information
2eb20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 about a single c
2eb30 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 olumn of the cur
2eb40 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 rent.** result r
2eb50 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 ow of a query.
2eb60 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 ^In every case t
2eb70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2eb80 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a t is a pointer.*
2eb90 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 * to the [prepar
2eba0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
2ebb0 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c at is being eval
2ebc0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 uated (the [sqli
2ebd0 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 te3_stmt*].** th
2ebe0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 at was returned
2ebf0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 from [sqlite3_pr
2ec00 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f epare_v2()] or o
2ec10 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e ne of its varian
2ec20 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 ts).** and the s
2ec30 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
2ec40 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
2ec50 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 he column for wh
2ec60 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a ich information.
2ec70 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 ** should be ret
2ec80 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 urned. ^The left
2ec90 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 most column of t
2eca0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 he result set ha
2ecb0 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a s the index 0..*
2ecc0 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 * ^The number of
2ecd0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
2ece0 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 result can be de
2ecf0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a termined using.*
2ed00 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
2ed10 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a n_count()]..**.*
2ed20 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 * If the SQL sta
2ed30 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
2ed40 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 currently point
2ed50 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 to a valid row,
2ed60 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c or if the.** col
2ed70 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 umn index is out
2ed80 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 of range, the r
2ed90 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e esult is undefin
2eda0 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 ed..** These rou
2edb0 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 tines may only b
2edc0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 e called when th
2edd0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
2ede0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
2edf0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 3_step()] has re
2ee00 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
2ee10 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a OW] and neither.
2ee20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
2ee30 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 t()] nor [sqlite
2ee40 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 3_finalize()] ha
2ee50 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 ve been called s
2ee60 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 ubsequently..**
2ee70 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 If any of these
2ee80 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
2ee90 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 led after [sqlit
2eea0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a e3_reset()] or.*
2eeb0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c * [sqlite3_final
2eec0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 ize()] or after
2eed0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2eee0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a has returned.**
2eef0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
2ef00 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f than [SQLITE_RO
2ef10 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 W], the results
2ef20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
2ef30 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 * If [sqlite3_st
2ef40 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ep()] or [sqlite
2ef50 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
2ef60 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2ef70 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 )].** are called
2ef80 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e from a differen
2ef90 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 t thread while a
2efa0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
2efb0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 ines.** are pend
2efc0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ing, then the re
2efd0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
2efe0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
2eff0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2f000 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ype() routine re
2f010 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 turns the.** [SQ
2f020 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 LITE_INTEGER | d
2f030 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f atatype code] fo
2f040 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 r the initial da
2f050 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 ta type.** of th
2f060 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e e result column.
2f070 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
2f080 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 value is one of
2f090 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d [SQLITE_INTEGER]
2f0a0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f ,.** [SQLITE_FLO
2f0b0 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 AT], [SQLITE_TEX
2f0c0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 T], [SQLITE_BLOB
2f0d0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 ], or [SQLITE_NU
2f0e0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a LL]. The value.
2f0f0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
2f100 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
2f110 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 pe() is only mea
2f120 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 ningful if no ty
2f130 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e pe.** conversion
2f140 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 s have occurred
2f150 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c as described bel
2f160 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 ow. After a typ
2f170 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a e conversion,.**
2f180 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
2f190 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
2f1a0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
2f1b0 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 undefined. Futu
2f1c0 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f re.** versions o
2f1d0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 f SQLite may cha
2f1e0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 nge the behavior
2f1f0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 of sqlite3_colu
2f200 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c mn_type().** fol
2f210 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f lowing a type co
2f220 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nversion..**.**
2f230 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2f240 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
2f250 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 8 string then th
2f260 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2f270 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 _bytes().** rout
2f280 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
2f290 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2f2a0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
2f2b0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
2f2c0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
2f2d0 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 TF-16 string, th
2f2e0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2f2f0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 n_bytes() conver
2f300 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
2f310 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 to UTF-8 and th
2f320 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e en returns the n
2f330 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a umber of bytes..
2f340 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
2f350 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
2f360 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
2f370 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2f380 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
2f390 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
2f3a0 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
2f3b0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 lue to a UTF-8 s
2f3c0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
2f3d0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
2f3e0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2f3f0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
2f400 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 the result is NU
2f410 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 LL, then sqlite3
2f420 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
2f430 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
2f440 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2f450 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
2f460 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 UTF-16 string th
2f470 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
2f480 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a olumn_bytes16().
2f490 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
2f4a0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2f4b0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 bytes in that B
2f4c0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
2f4d0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
2f4e0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 is a UTF-8 stri
2f4f0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
2f500 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2f510 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
2f520 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
2f530 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 16 and then retu
2f540 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2f550 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 f bytes..** ^If
2f560 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2f570 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 numeric value th
2f580 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2f590 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 n_bytes16() uses
2f5a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
2f5b0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
2f5c0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
2f5d0 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e o a UTF-16 strin
2f5e0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
2f5f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2f600 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
2f610 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
2f620 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
2f630 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2f640 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 umn_bytes16() re
2f650 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
2f660 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 * ^The values re
2f670 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2f680 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2f690 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 )] and .** [sqli
2f6a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2f6b0 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 16()] do not inc
2f6c0 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 lude the zero te
2f6d0 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 rminators at the
2f6e0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 end.** of the s
2f6f0 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 tring. ^For cla
2f700 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 rity: the values
2f710 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
2f720 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2f730 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 bytes()] and [sq
2f740 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2f750 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 es16()] are the
2f760 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 number of.** byt
2f770 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 es in the string
2f780 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
2f790 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
2f7a0 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 **.** ^Strings r
2f7b0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
2f7c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2f7d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2f7e0 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a umn_text16(),.**
2f7f0 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 even empty stri
2f800 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 ngs, are always
2f810 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e zero-terminated.
2f820 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a ^The return.**
2f830 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
2f840 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2f850 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e ) for a zero-len
2f860 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 gth BLOB is a NU
2f870 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
2f880 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 * <b>Warning:</b
2f890 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 > ^The object re
2f8a0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2f8b0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2f8c0 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 )] is an.** [unp
2f8d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2f8e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 _value] object.
2f8f0 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 In a multithrea
2f900 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c ded environment,
2f910 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 .** an unprotect
2f920 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2f930 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 object may only
2f940 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 be used safely
2f950 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 with.** [sqlite3
2f960 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 _bind_value()] a
2f970 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 nd [sqlite3_resu
2f980 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 lt_value()]..**
2f990 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 If the [unprotec
2f9a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2f9b0 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e e] object return
2f9c0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 ed by.** [sqlite
2f9d0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 3_column_value()
2f9e0 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 ] is used in any
2f9f0 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c other way, incl
2fa00 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 uding calls.** t
2fa10 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 o routines like
2fa20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 [sqlite3_value_i
2fa30 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f nt()], [sqlite3_
2fa40 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a value_text()],.*
2fa50 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 * or [sqlite3_va
2fa60 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 lue_bytes()], th
2fa70 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f e behavior is no
2fa80 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a t threadsafe..**
2fa90 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
2faa0 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f es attempt to co
2fab0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 nvert the value
2fac0 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 where appropriat
2fad0 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d e. ^For.** exam
2fae0 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 ple, if the inte
2faf0 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 rnal representat
2fb00 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 ion is FLOAT and
2fb10 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a a text result.*
2fb20 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 * is requested,
2fb30 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
2fb40 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 f()] is used int
2fb50 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f ernally to perfo
2fb60 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 rm the.** conver
2fb70 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c sion automatical
2fb80 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f ly. ^(The follo
2fb90 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 wing table detai
2fba0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f ls the conversio
2fbb0 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 ns.** that are a
2fbc0 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 pplied:.**.** <b
2fbd0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 lockquote>.** <t
2fbe0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e able border="1">
2fbf0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 .** <tr><th> Int
2fc00 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 ernal<br>Type <t
2fc10 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e h> Requested<br>
2fc20 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 Type <th> Conve
2fc30 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e rsion.**.** <tr>
2fc40 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
2fc50 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
2fc60 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a > Result is 0.**
2fc70 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
2fc80 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 <td> FLOAT
2fc90 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
2fca0 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 0.0.** <tr><td>
2fcb0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
2fcc0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 TEXT <td> Re
2fcd0 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 sult is a NULL p
2fce0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 ointer.** <tr><t
2fcf0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
2fd00 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
2fd10 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c Result is a NULL
2fd20 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
2fd30 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
2fd40 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
2fd50 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 > Convert from i
2fd60 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a nteger to float.
2fd70 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 ** <tr><td> INTE
2fd80 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 GER <td> TEXT
2fd90 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
2fda0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
2fdb0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c integer.** <tr><
2fdc0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
2fdd0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
2fde0 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 Same as INTEGER
2fdf0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 ->TEXT.** <tr><t
2fe00 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
2fe10 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
2fe20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 [CAST] to INTEGE
2fe30 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 R.** <tr><td> F
2fe40 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 LOAT <td> TE
2fe50 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 XT <td> ASCII
2fe60 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
2fe70 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c e float.** <tr><
2fe80 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
2fe90 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
2fea0 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a [CAST] to BLOB.
2feb0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 ** <tr><td> TEX
2fec0 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 T <td> INTEGE
2fed0 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 R <td> [CAST]
2fee0 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 to INTEGER.** <t
2fef0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
2ff00 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
2ff10 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 td> [CAST] to RE
2ff20 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 AL.** <tr><td>
2ff30 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 TEXT <td> B
2ff40 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 LOB <td> No c
2ff50 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 hange.** <tr><td
2ff60 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
2ff70 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b INTEGER <td> [
2ff80 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 CAST] to INTEGER
2ff90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
2ffa0 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 OB <td> FLOA
2ffb0 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d T <td> [CAST]
2ffc0 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e to REAL.** <tr>
2ffd0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 <td> BLOB <t
2ffe0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
2fff0 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 > Add a zero ter
30000 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 minator if neede
30010 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a d.** </table>.**
30020 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e </blockquote>)^
30030 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
30040 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 when type conve
30050 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f rsions occur, po
30060 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 inters returned
30070 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c by prior.** call
30080 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
30090 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 umn_blob(), sqli
300a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
300b0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c ), and/or.** sql
300c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
300d0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 16() may be inva
300e0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 lidated..** Type
300f0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 conversions and
30100 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 pointer invalid
30110 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 ations might occ
30120 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c ur.** in the fol
30130 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a lowing cases:.**
30140 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
30150 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
30160 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 tent is a BLOB a
30170 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
30180 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 n_text() or.**
30190 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
301a0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 mn_text16() is c
301b0 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 alled. A zero-t
301c0 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a erminator might.
301d0 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 ** need to
301e0 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 be added to the
301f0 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 string.</li>.**
30200 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c <li> The initial
30210 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d content is UTF-
30220 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 8 text and sqlit
30230 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
30240 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 6() or.** s
30250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
30260 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 xt16() is called
30270 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d . The content m
30280 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 ust be converted
30290 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d .** to UTF-
302a0 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 16.</li>.** <li>
302b0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
302c0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 tent is UTF-16 t
302d0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ext and sqlite3_
302e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f column_bytes() o
302f0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 r.** sqlite
30300 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
30310 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 is called. The
30320 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 content must be
30330 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 converted.**
30340 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e to UTF-8.</li>
30350 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
30360 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 ^Conversions bet
30370 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e ween UTF-16be an
30380 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 d UTF-16le are a
30390 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c lways done in pl
303a0 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f ace and do.** no
303b0 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 t invalidate a p
303c0 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 rior pointer, th
303d0 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 ough of course t
303e0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
303f0 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 e buffer.** that
30400 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 the prior point
30410 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 er references wi
30420 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 ll have been mod
30430 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 ified. Other ki
30440 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 nds.** of conver
30450 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e sion are done in
30460 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 place when it i
30470 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 s possible, but
30480 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a sometimes they.*
30490 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 * are not possib
304a0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 le and in those
304b0 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e cases prior poin
304c0 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 ters are invalid
304d0 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ated..**.** The
304e0 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 safest policy is
304f0 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 to invoke these
30500 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 routines.** in
30510 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
30520 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a wing ways:.**.**
30530 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 <ul>.** <li>sq
30540 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
30550 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 t() followed by
30560 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
30570 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 ytes()</li>.**
30580 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
30590 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 mn_blob() follow
305a0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
305b0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 lumn_bytes()</li
305c0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
305d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
305e0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
305f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
30600 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c es16()</li>.** <
30610 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 /ul>.**.** In ot
30620 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 her words, you s
30630 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 hould call sqlit
30640 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
30650 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c ,.** sqlite3_col
30660 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 umn_blob(), or s
30670 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
30680 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 xt16() first to
30690 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 force the result
306a0 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 .** into the des
306b0 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 ired format, the
306c0 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 n invoke sqlite3
306d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
306e0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
306f0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 lumn_bytes16() t
30700 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 o find the size
30710 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 of the result.
30720 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 Do not mix calls
30730 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 .** to sqlite3_c
30740 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 olumn_text() or
30750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
30760 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 lob() with calls
30770 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 to.** sqlite3_c
30780 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c olumn_bytes16(),
30790 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 and do not mix
307a0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
307b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
307c0 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 .** with calls t
307d0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
307e0 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 _bytes()..**.**
307f0 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 ^The pointers re
30800 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 turned are valid
30810 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f until a type co
30820 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 nversion occurs
30830 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 as.** described
30840 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 above, or until
30850 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
30860 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 or [sqlite3_res
30870 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c et()] or.** [sql
30880 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
30890 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 is called. ^Th
308a0 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 e memory space u
308b0 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 sed to hold stri
308c0 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 ngs.** and BLOBs
308d0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 is freed automa
308e0 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d tically. Do <em
308f0 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 >not</em> pass t
30900 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
30910 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 rned.** from [sq
30920 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
30930 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 b()], [sqlite3_c
30940 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 olumn_text()], e
30950 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c tc. into.** [sql
30960 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
30970 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 .** ^(If a memor
30980 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
30990 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 or occurs during
309a0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 the evaluation
309b0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 of any.** of the
309c0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 se routines, a d
309d0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 efault value is
309e0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 returned. The d
309f0 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 efault value.**
30a00 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e is either the in
30a10 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f teger 0, the flo
30a20 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 ating point numb
30a30 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c er 0.0, or a NUL
30a40 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 L.** pointer. S
30a50 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
30a60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 to [sqlite3_errc
30a70 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 ode()] will retu
30a80 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f rn.** [SQLITE_NO
30a90 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 MEM].)^.*/.const
30aa0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
30ab0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 olumn_blob(sqlit
30ac0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
30ad0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ol);.int sqlite3
30ae0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 _column_bytes(sq
30af0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
30b00 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 iCol);.int sqli
30b10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
30b20 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
30b30 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 , int iCol);.dou
30b40 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ble sqlite3_colu
30b50 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 mn_double(sqlite
30b60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
30b70 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
30b80 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 column_int(sqlit
30b90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
30ba0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 ol);.sqlite3_int
30bb0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 64 sqlite3_colum
30bc0 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f n_int64(sqlite3_
30bd0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
30be0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 ;.const unsigned
30bf0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
30c00 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 olumn_text(sqlit
30c10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
30c20 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 ol);.const void
30c30 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
30c40 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
30c50 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
30c60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
30c70 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 umn_type(sqlite3
30c80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
30c90 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 );.sqlite3_value
30ca0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
30cb0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 _value(sqlite3_s
30cc0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
30cd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
30ce0 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 : Destroy A Prep
30cf0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
30d00 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 bject.** DESTRUC
30d10 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d TOR: sqlite3_stm
30d20 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c t.**.** ^The sql
30d30 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 ite3_finalize()
30d40 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c function is call
30d50 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b ed to delete a [
30d60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
30d70 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 nt]..** ^If the
30d80 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c most recent eval
30d90 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 uation of the st
30da0 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 atement encounte
30db0 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a red no errors.**
30dc0 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 or if the state
30dd0 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 ment is never be
30de0 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 en evaluated, th
30df0 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c en sqlite3_final
30e00 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a ize() returns.**
30e10 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 SQLITE_OK. ^If
30e20 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
30e30 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 evaluation of s
30e40 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 tatement S faile
30e50 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 d, then.** sqlit
30e60 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 e3_finalize(S) r
30e70 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f eturns the appro
30e80 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f priate [error co
30e90 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e de] or.** [exten
30ea0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e ded error code].
30eb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
30ec0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 te3_finalize(S)
30ed0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 routine can be c
30ee0 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 alled at any poi
30ef0 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 nt during.** the
30f00 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b life cycle of [
30f10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
30f20 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 nt] S:.** before
30f30 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 statement S is
30f40 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 ever evaluated,
30f50 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 after.** one or
30f60 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 more calls to [s
30f70 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c qlite3_reset()],
30f80 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 or after any ca
30f90 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 ll.** to [sqlite
30fa0 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 3_step()] regard
30fb0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
30fc0 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 or not the state
30fd0 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 ment has.** comp
30fe0 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e leted execution.
30ff0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 .**.** ^Invoking
31000 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
31010 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f e() on a NULL po
31020 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c inter is a harml
31030 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a ess no-op..**.**
31040 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
31050 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 must finalize e
31060 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 very [prepared s
31070 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 tatement] in ord
31080 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 er to avoid.** r
31090 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 esource leaks.
310a0 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 It is a grievous
310b0 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 error for the a
310c0 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 pplication to tr
310d0 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 y to use.** a pr
310e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
310f0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 after it has be
31100 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 en finalized. A
31110 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 ny use of a prep
31120 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e ared.** statemen
31130 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 t after it has b
31140 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 een finalized ca
31150 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 n result in unde
31160 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 fined and.** und
31170 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f esirable behavio
31180 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 r such as segfau
31190 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 lts and heap cor
311a0 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 ruption..*/.int
311b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
311c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
311d0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
311e0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 PI3REF: Reset A
311f0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
31200 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 nt Object.** MET
31210 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
31220 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 t.**.** The sqli
31230 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 te3_reset() func
31240 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 tion is called t
31250 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 o reset a [prepa
31260 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
31270 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f * object back to
31280 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 its initial sta
31290 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 te, ready to be
312a0 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 re-executed..**
312b0 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 ^Any SQL stateme
312c0 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 nt variables tha
312d0 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 t had values bou
312e0 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 nd to them using
312f0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
31300 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c _bind_blob | sql
31310 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 ite3_bind_*() AP
31320 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 I] retain their
31330 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b values..** Use [
31340 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 sqlite3_clear_bi
31350 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 ndings()] to res
31360 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e et the bindings.
31370 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c .**.** ^The [sql
31380 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 ite3_reset(S)] i
31390 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 nterface resets
313a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
313b0 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 atement] S.** ba
313c0 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e ck to the beginn
313d0 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 ing of its progr
313e0 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 am..**.** ^If th
313f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
31400 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
31410 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a tep(S)] for the.
31420 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
31430 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e tement] S return
31440 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
31450 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d or [SQLITE_DONE]
31460 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 ,.** or if [sqli
31470 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 te3_step(S)] has
31480 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 never before be
31490 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a en called on S,.
314a0 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 ** then [sqlite3
314b0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 _reset(S)] retur
314c0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a ns [SQLITE_OK]..
314d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
314e0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
314f0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
31500 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
31510 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
31520 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 nt] S indicated
31530 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a an error, then.*
31540 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
31550 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 (S)] returns an
31560 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 appropriate [err
31570 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 or code]..**.**
31580 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 ^The [sqlite3_re
31590 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 set(S)] interfac
315a0 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 e does not chang
315b0 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 e the values.**
315c0 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f of any [sqlite3_
315d0 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e bind_blob|bindin
315e0 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 gs] on the [prep
315f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
31600 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 S..*/.int sqlite
31610 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 3_reset(sqlite3_
31620 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
31630 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
31640 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e reate Or Redefin
31650 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a e SQL Functions.
31660 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 ** KEYWORDS: {fu
31670 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 nction creation
31680 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 routines}.** KEY
31690 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 WORDS: {applicat
316a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
316b0 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 function}.** KEY
316c0 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 WORDS: {applicat
316d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
316e0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 functions}.** ME
316f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
31700 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 .** ^These funct
31710 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 ions (collective
31720 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e ly known as "fun
31730 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 ction creation r
31740 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 outines").** are
31750 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c used to add SQL
31760 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 functions or ag
31770 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 gregates or to r
31780 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 edefine the beha
31790 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 vior.** of exist
317a0 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ing SQL function
317b0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e s or aggregates.
317c0 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 The only diffe
317d0 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a rences between.*
317e0 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * these routines
317f0 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e are the text en
31800 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 coding expected
31810 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e for.** the secon
31820 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 d parameter (the
31830 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e name of the fun
31840 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 ction being crea
31850 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 ted).** and the
31860 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 presence or abse
31870 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 nce of a destruc
31880 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 tor callback for
31890 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
318a0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 ion data pointer
318b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
318c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
318d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
318e0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 nnection] to whi
318f0 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 ch the SQL.** fu
31900 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 nction is to be
31910 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 added. ^If an a
31920 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 pplication uses
31930 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 more than one da
31940 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
31950 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 tion then applic
31960 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
31970 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 L functions must
31980 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 be added.** to
31990 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f each database co
319a0 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 nnection separat
319b0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ely..**.** ^The
319c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
319d0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
319e0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
319f0 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f to be created o
31a00 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 r.** redefined.
31a10 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 ^The length of
31a20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 the name is limi
31a30 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 ted to 255 bytes
31a40 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 in a UTF-8.** r
31a50 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 epresentation, e
31a60 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 xclusive of the
31a70 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e zero-terminator.
31a80 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 ^Note that the
31a90 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 name.** length
31aa0 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d limit is in UTF-
31ab0 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 8 bytes, not cha
31ac0 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d racters nor UTF-
31ad0 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 16 bytes. .** ^
31ae0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 Any attempt to c
31af0 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e reate a function
31b00 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e with a longer n
31b10 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 ame.** will resu
31b20 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 lt in [SQLITE_MI
31b30 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 SUSE] being retu
31b40 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 rned..**.** ^The
31b50 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
31b60 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 (nArg).** is th
31b70 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 e number of argu
31b80 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 ments that the S
31b90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
31ba0 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 * aggregate take
31bb0 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 s. ^If this para
31bc0 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 meter is -1, the
31bd0 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 n the SQL functi
31be0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
31bf0 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 te may take any
31c00 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
31c10 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e nts between 0 an
31c20 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 d the limit.** s
31c30 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c et by [sqlite3_l
31c40 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 imit]([SQLITE_LI
31c50 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 MIT_FUNCTION_ARG
31c60 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 ]). If the thir
31c70 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 d.** parameter i
31c80 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f s less than -1 o
31c90 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 r greater than 1
31ca0 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 27 then the beha
31cb0 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 vior is.** undef
31cc0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ined..**.** ^The
31cd0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
31ce0 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 r, eTextRep, spe
31cf0 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b cifies what.** [
31d00 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 SQLITE_UTF8 | te
31d10 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 xt encoding] thi
31d20 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 s SQL function p
31d30 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 refers for.** it
31d40 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 s parameters. T
31d50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
31d60 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 hould set this p
31d70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b arameter to.** [
31d80 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 SQLITE_UTF16LE]
31d90 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 if the function
31da0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
31db0 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 nvokes .** [sqli
31dc0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
31dd0 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 le()] on an inpu
31de0 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 t, or [SQLITE_UT
31df0 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a F16BE] if the.**
31e00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
31e10 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 invokes [sqlite3
31e20 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 _value_text16be(
31e30 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 )] on an input,
31e40 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 or.** [SQLITE_UT
31e50 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 F16] if [sqlite3
31e60 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d _value_text16()]
31e70 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 is used, or [SQ
31e80 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 LITE_UTF8].** ot
31e90 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 herwise. ^The s
31ea0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ame SQL function
31eb0 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 may be register
31ec0 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 ed multiple time
31ed0 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 s using.** diffe
31ee0 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 rent preferred t
31ef0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 ext encodings, w
31f00 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d ith different im
31f10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f plementations fo
31f20 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 r.** each encodi
31f30 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c ng..** ^When mul
31f40 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
31f50 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
31f60 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 e function are a
31f70 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 vailable, SQLite
31f80 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 .** will pick th
31f90 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c e one that invol
31fa0 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d ves the least am
31fb0 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e ount of data con
31fc0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e version..**.** ^
31fd0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
31fe0 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 eter may optiona
31ff0 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 lly be ORed with
32000 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 [SQLITE_DETERMI
32010 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 NISTIC].** to si
32020 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 gnal that the fu
32030 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 nction will alwa
32040 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 ys return the sa
32050 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a me result given.
32060 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 ** the same inpu
32070 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 ts within a sing
32080 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 le SQL statement
32090 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 . Most SQL func
320a0 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 tions are.** det
320b0 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 erministic. The
320c0 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f built-in [rando
320d0 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f m()] SQL functio
320e0 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 n is an example
320f0 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e of a.** function
32100 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 that is not det
32110 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 erministic. The
32120 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c SQLite query pl
32130 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f anner is able to
32140 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 .** perform addi
32150 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 tional optimizat
32160 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e ions on determin
32170 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c istic functions,
32180 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 so use.** of th
32190 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d e [SQLITE_DETERM
321a0 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 INISTIC] flag is
321b0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 recommended whe
321c0 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a re possible..**.
321d0 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 ** ^(The fifth p
321e0 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 arameter is an a
321f0 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 rbitrary pointer
32200 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 . The implement
32210 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 ation of the.**
32220 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 function can gai
32230 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 n access to this
32240 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b pointer using [
32250 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
32260 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 a()].)^.**.** ^T
32270 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 he sixth, sevent
32280 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 h and eighth par
32290 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 ameters, xFunc,
322a0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
322b0 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 , are.** pointer
322c0 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 s to C-language
322d0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 functions that i
322e0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c mplement the SQL
322f0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
32300 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 aggregate. ^A sc
32310 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f alar SQL functio
32320 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d n requires an im
32330 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
32340 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c the xFunc.** cal
32350 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c lback only; NULL
32360 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 pointers must b
32370 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
32380 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
32390 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 .** parameters.
323a0 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 ^An aggregate SQ
323b0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 L function requi
323c0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 res an implement
323d0 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a ation of xStep.*
323e0 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 * and xFinal and
323f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 NULL pointer mu
32400 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 st be passed for
32410 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 xFunc. ^To dele
32420 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a te an existing.*
32430 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f * SQL function o
32440 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 r aggregate, pas
32450 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 s NULL pointers
32460 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 for all three fu
32470 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 nction.** callba
32480 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 cks..**.** ^(If
32490 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 the ninth parame
324a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ter to sqlite3_c
324b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
324c0 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 2() is not NULL,
324d0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 .** then it is d
324e0 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 estructor for th
324f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 e application da
32500 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 ta pointer. .**
32510 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
32520 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 s invoked when t
32530 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 he function is d
32540 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 eleted, either b
32550 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c y being.** overl
32560 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 oaded or when th
32570 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
32580 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a ction closes.)^.
32590 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 ** ^The destruct
325a0 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b or is also invok
325b0 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 ed if the call t
325c0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 o.** sqlite3_cre
325d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
325e0 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 ) fails..** ^Whe
325f0 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 n the destructor
32600 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 callback of the
32610 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 tenth parameter
32620 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a is invoked, it.
32630 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 ** is passed a s
32640 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
32650 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f hich is a copy o
32660 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
32670 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 n data .** point
32680 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 er which was the
32690 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 fifth parameter
326a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 to sqlite3_crea
326b0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 te_function_v2()
326c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 ..**.** ^It is p
326d0 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 ermitted to regi
326e0 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d ster multiple im
326f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
32700 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e the same.** fun
32710 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 ctions with the
32720 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 same name but wi
32730 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 th either differ
32740 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a ing numbers of.*
32750 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 * arguments or d
32760 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 iffering preferr
32770 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ed text encoding
32780 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c s. ^SQLite will
32790 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c use.** the impl
327a0 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 ementation that
327b0 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 most closely mat
327c0 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 ches the way in
327d0 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c which the.** SQL
327e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 function is use
327f0 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 d. ^A function
32800 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
32810 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 ith a non-negati
32820 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d ve.** nArg param
32830 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 eter is a better
32840 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 match than a fu
32850 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
32860 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 ation with.** a
32870 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 negative nArg.
32880 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 ^A function wher
32890 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 e the preferred
328a0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a text encoding.**
328b0 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 matches the dat
328c0 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 abase encoding i
328d0 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 s a better.** ma
328e0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 tch than a funct
328f0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e ion where the en
32900 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 coding is differ
32910 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e ent. .** ^A fun
32920 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
32930 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 encoding differe
32940 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 nce is between U
32950 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 TF16le and UTF16
32960 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 be.** is a close
32970 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 r match than a f
32980 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
32990 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 e encoding diffe
329a0 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 rence is.** betw
329b0 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 een UTF8 and UTF
329c0 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 16..**.** ^Built
329d0 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 -in functions ma
329e0 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 y be overloaded
329f0 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 by new applicati
32a00 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
32a10 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 ions..**.** ^An
32a20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
32a30 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ned function is
32a40 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c permitted to cal
32a50 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 l other.** SQLit
32a60 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 e interfaces. H
32a70 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c owever, such cal
32a80 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 ls must not.** c
32a90 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 lose the databas
32aa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 e connection nor
32ab0 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 finalize or res
32ac0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a et the prepared.
32ad0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 ** statement in
32ae0 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 which the functi
32af0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
32b00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 /.int sqlite3_cr
32b10 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 eate_function(.
32b20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 sqlite3 *db,.
32b30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e const char *zFun
32b40 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 ctionName,. int
32b50 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 nArg,. int eTe
32b60 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 xtRep,. void *p
32b70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 App,. void (*xF
32b80 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
32b90 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
32ba0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
32bb0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
32bc0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
32bd0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
32be0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
32bf0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
32c00 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c ext*).);.int sql
32c10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
32c20 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 tion16(. sqlite
32c30 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 3 *db,. const v
32c40 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 oid *zFunctionNa
32c50 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
32c60 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
32c70 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
32c80 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
32c90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
32ca0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
32cb0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
32cc0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
32cd0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
32ce0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
32cf0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
32d00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 ite3_context*).)
32d10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 ;.int sqlite3_cr
32d20 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 eate_function_v2
32d30 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
32d40 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
32d50 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 FunctionName,.
32d60 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 int nArg,. int
32d70 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 eTextRep,. void
32d80 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 *pApp,. void (
32d90 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f *xFunc)(sqlite3_
32da0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
32db0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
32dc0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 void (*xStep)(s
32dd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
32de0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
32df0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
32e00 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 Final)(sqlite3_c
32e10 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 ontext*),. void
32e20 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 (*xDestroy)(void
32e30 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *).);../*.** CAP
32e40 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f I3REF: Text Enco
32e50 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 dings.**.** Thes
32e60 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e e constant defin
32e70 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 e integer codes
32e80 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 that represent t
32e90 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 he various.** te
32ea0 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 xt encodings sup
32eb0 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 ported by SQLite
32ec0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
32ed0 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 ITE_UTF8
32ee0 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 1 /* IMP:
32ef0 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f R-37514-35566 */
32f00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
32f10 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 UTF16LE 2
32f20 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 /* IMP: R-03
32f30 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 371-37637 */.#de
32f40 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
32f50 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20 20 6BE 3
32f60 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d /* IMP: R-51971-
32f70 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 34154 */.#define
32f80 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 SQLITE_UTF16
32f90 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 4 /* U
32fa0 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f se native byte o
32fb0 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rder */.#define
32fc0 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 SQLITE_ANY
32fd0 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 5 /* De
32fe0 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 precated */.#def
32ff0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
33000 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f _ALIGNED 8 /
33010 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
33020 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 _collation only
33030 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
33040 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 EF: Function Fla
33050 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 gs.**.** These c
33060 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 onstants may be
33070 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 ORed together wi
33080 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 th the .** [SQLI
33090 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 TE_UTF8 | prefer
330a0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
330b0 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 g] as the fourth
330c0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
330d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
330e0 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 function()], [sq
330f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
33100 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a ction16()], or.*
33110 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
33120 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d e_function_v2()]
33130 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
33140 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 ITE_DETERMINISTI
33150 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a C 0x800../*.*
33160 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 * CAPI3REF: Depr
33170 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 ecated Functions
33180 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a .** DEPRECATED.*
33190 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
331a0 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 ions are [deprec
331b0 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 ated]. In order
331c0 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 to maintain.**
331d0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
331e0 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 ibility with old
331f0 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 er code, these f
33200 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 unctions continu
33210 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 e .** to be supp
33220 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c orted. However,
33230 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e new application
33240 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a s should avoid.*
33250 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 * the use of the
33260 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 se functions. T
33270 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 o encourage prog
33280 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 rammers to avoid
33290 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 .** these functi
332a0 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 ons, we will not
332b0 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68 explain what th
332c0 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 ey do..*/.#ifnde
332d0 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 f SQLITE_OMIT_DE
332e0 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f PRECATED.SQLITE_
332f0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 DEPRECATED int s
33300 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
33310 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 _count(sqlite3_c
33320 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 ontext*);.SQLITE
33330 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
33340 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 sqlite3_expired(
33350 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
33360 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
33370 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 D int sqlite3_tr
33380 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 ansfer_bindings(
33390 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 sqlite3_stmt*, s
333a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 qlite3_stmt*);.S
333b0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
333c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f int sqlite3_glo
333d0 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 bal_recover(void
333e0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
333f0 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 ATED void sqlite
33400 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 3_thread_cleanup
33410 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 (void);.SQLITE_D
33420 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 EPRECATED int sq
33430 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 lite3_memory_ala
33440 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a rm(void(*)(void*
33450 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 ,sqlite3_int64,i
33460 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 nt),.
33470 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a void*
33480 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b ,sqlite3_int64);
33490 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 .#endif../*.** C
334a0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 API3REF: Obtaini
334b0 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a ng SQL Values.**
334c0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
334d0 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 _value.**.** The
334e0 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c C-language impl
334f0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 ementation of SQ
33500 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 L functions and
33510 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a aggregates uses.
33520 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 ** this set of i
33530 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 nterface routine
33540 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
33550 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 parameter values
33560 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 on.** the funct
33570 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
33580 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 . .**.** The xF
33590 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 unc (for scalar
335a0 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 functions) or xS
335b0 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 tep (for aggrega
335c0 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a tes) parameters.
335d0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ** to [sqlite3_c
335e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
335f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
33600 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
33610 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 ()].** define ca
33620 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 llbacks that imp
33630 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 lement the SQL f
33640 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
33650 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 regates..** The
33660 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
33670 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 these callbacks
33680 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
33690 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b pointers to.** [
336a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
336b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
336c0 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 . There is one
336d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
336e0 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 object for.** ea
336f0 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ch parameter to
33700 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
33710 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 . These routine
33720 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a s are used to.**
33730 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 extract values
33740 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 from the [sqlite
33750 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
33760 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
33770 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 utines work only
33780 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 with [protected
33790 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
337a0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 objects..** Any
337b0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 attempt to use t
337c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e hese routines on
337d0 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 an [unprotected
337e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a sqlite3_value].
337f0 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 ** object result
33800 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 s in undefined b
33810 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e ehavior..**.** ^
33820 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 These routines w
33830 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 ork just like th
33840 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
33850 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 [column access f
33860 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 unctions].** exc
33870 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72 ept that these r
33880 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 outines take a s
33890 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 ingle [protected
338a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
338b0 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 object.** pointe
338c0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b r instead of a [
338d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 sqlite3_stmt*] p
338e0 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e ointer and an in
338f0 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d teger column num
33900 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ber..**.** ^The
33910 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
33920 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 xt16() interface
33930 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d extracts a UTF-
33940 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 16 string.** in
33950 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d the native byte-
33960 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 order of the hos
33970 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 t machine. ^The
33980 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
33990 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 e_text16be() and
339a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
339b0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 ext16le() interf
339c0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 aces.** extract
339d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 UTF-16 strings a
339e0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 s big-endian and
339f0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 little-endian r
33a00 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a espectively..**.
33a10 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
33a20 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
33a30 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ype() interface
33a40 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c attempts to appl
33a50 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 y.** numeric aff
33a60 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c inity to the val
33a70 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 ue. This means
33a80 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 that an attempt
33a90 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f is.** made to co
33aa0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 nvert the value
33ab0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 to an integer or
33ac0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e floating point.
33ad0 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 If.** such a c
33ae0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 onversion is pos
33af0 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f sible without lo
33b00 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f ss of informatio
33b10 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 n (in other.** w
33b20 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c ords, if the val
33b30 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 ue is a string t
33b40 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 hat looks like a
33b50 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e number).** then
33b60 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 the conversion
33b70 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f is performed. O
33b80 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 therwise no conv
33b90 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a ersion occurs..*
33ba0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e * The [SQLITE_IN
33bb0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 TEGER | datatype
33bc0 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 ] after conversi
33bd0 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 on is returned.)
33be0 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 ^.**.** Please p
33bf0 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 ay particular at
33c00 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 tention to the f
33c10 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 act that the poi
33c20 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a nter returned.**
33c30 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 from [sqlite3_v
33c40 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 alue_blob()], [s
33c50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
33c60 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c t()], or.** [sql
33c70 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
33c80 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6()] can be inva
33c90 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 lidated by a sub
33ca0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a sequent call to.
33cb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ** [sqlite3_valu
33cc0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c e_bytes()], [sql
33cd0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
33ce0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 16()], [sqlite3_
33cf0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a value_text()],.*
33d00 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 * or [sqlite3_va
33d10 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a lue_text16()]..*
33d20 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
33d30 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c nes must be call
33d40 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
33d50 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 thread as.** th
33d60 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 e SQL function t
33d70 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 hat supplied the
33d80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a [sqlite3_value*
33d90 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f ] parameters..*/
33da0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
33db0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
33dc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
33dd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c .int sqlite3_val
33de0 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 ue_bytes(sqlite3
33df0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
33e00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
33e10 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 s16(sqlite3_valu
33e20 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 e*);.double sqli
33e30 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 te3_value_double
33e40 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
33e50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
33e60 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f lue_int(sqlite3_
33e70 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 value*);.sqlite3
33e80 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 _int64 sqlite3_v
33e90 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 alue_int64(sqlit
33ea0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 e3_value*);.cons
33eb0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 t unsigned char
33ec0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
33ed0 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ext(sqlite3_valu
33ee0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
33ef0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
33f00 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 ext16(sqlite3_va
33f10 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 lue*);.const voi
33f20 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
33f30 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
33f40 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
33f50 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
33f60 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 alue_text16be(sq
33f70 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
33f80 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
33f90 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
33fa0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
33fb0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 e3_value_numeric
33fc0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
33fd0 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lue*);../*.** CA
33fe0 50 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 PI3REF: Copy And
33ff0 20 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 Free SQL Values
34000 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
34010 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 te3_value.**.**
34020 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
34030 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 ue_dup(V) interf
34040 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ace makes a copy
34050 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
34060 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 _value].** objec
34070 74 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 t D and returns
34080 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 a pointer to tha
34090 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 t copy. ^The [s
340a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 qlite3_value] re
340b0 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b turned.** is a [
340c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
340d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
340e0 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 even if the inpu
340f0 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 t is not..** ^Th
34100 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
34110 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 dup(V) interface
34120 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 returns NULL if
34130 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 V is NULL or if
34140 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c a.** memory all
34150 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a ocation fails..*
34160 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
34170 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 3_value_free(V)
34180 69 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 20 interface frees
34190 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 an [sqlite3_valu
341a0 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 e] object.** pre
341b0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 viously obtained
341c0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 from [sqlite3_v
341d0 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 alue_dup()]. ^I
341e0 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f V is a NULL po
341f0 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 inter.** then sq
34200 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 lite3_value_free
34210 28 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 (V) is a harmles
34220 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 s no-op..*/.SQLI
34230 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
34240 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 sqlite3_value *s
34250 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 qlite3_value_dup
34260 28 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 (const sqlite3_v
34270 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 alue*);.SQLITE_E
34280 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 XPERIMENTAL void
34290 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 sqlite3_value_f
342a0 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ree(sqlite3_valu
342b0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 e*);../*.** CAPI
342c0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 3REF: Obtain Agg
342d0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 regate Function
342e0 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f Context.** METHO
342f0 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 D: sqlite3_conte
34300 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 xt.**.** Impleme
34310 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 ntations of aggr
34320 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
34330 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 ons use this.**
34340 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 routine to alloc
34350 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 ate memory for s
34360 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 toring their sta
34370 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 te..**.** ^The f
34380 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 irst time the sq
34390 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
343a0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 context(C,N) rou
343b0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a tine is called .
343c0 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 ** for a particu
343d0 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 lar aggregate fu
343e0 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a nction, SQLite.*
343f0 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 * allocates N of
34400 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 memory, zeroes
34410 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c out that memory,
34420 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 and returns a p
34430 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
34440 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e new memory. ^On
34450 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 second and subs
34460 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a equent calls to.
34470 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 ** sqlite3_aggre
34480 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 gate_context() f
34490 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 or the same aggr
344a0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 egate function i
344b0 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 nstance,.** the
344c0 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 same buffer is r
344d0 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 eturned. Sqlite
344e0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
344f0 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c ext() is normall
34500 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 y.** called once
34510 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 for each invoca
34520 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 tion of the xSte
34530 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 p callback and t
34540 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 hen one.** last
34550 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 time when the xF
34560 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 inal callback is
34570 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 invoked. ^(Whe
34580 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a n no rows match.
34590 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 ** an aggregate
345a0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 query, the xStep
345b0 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 () callback of t
345c0 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e he aggregate fun
345d0 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 ction.** impleme
345e0 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 ntation is never
345f0 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e called and xFin
34600 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 al() is called e
34610 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 xactly once..**
34620 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 In those cases,
34630 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
34640 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 e_context() migh
34650 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 t be called for
34660 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d the.** first tim
34670 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 e from within xF
34680 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 inal().)^.**.**
34690 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 ^The sqlite3_agg
346a0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
346b0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ,N) routine retu
346c0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
346d0 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 er .** when firs
346e0 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 t called if N is
346f0 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 less than or eq
34700 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 ual to zero or i
34710 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c f a memory.** al
34720 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 locate error occ
34730 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 urs..**.** ^(The
34740 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 amount of space
34750 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 allocated by sq
34760 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
34770 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a context(C,N) is.
34780 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 ** determined by
34790 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 the N parameter
347a0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 on first succes
347b0 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e sful call. Chan
347c0 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 ging the.** valu
347d0 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 e of N in subseq
347e0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c uent call to sql
347f0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
34800 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a ontext() within.
34810 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 ** the same aggr
34820 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 egate function i
34830 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 nstance will not
34840 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f resize the memo
34850 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e ry.** allocation
34860 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 .)^ Within the
34870 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c xFinal callback,
34880 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 it is customary
34890 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 to set.** N=0 i
348a0 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 n calls to sqlit
348b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
348c0 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 text(C,N) so tha
348d0 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 t no .** pointle
348e0 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ss memory alloca
348f0 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a tions occur..**.
34900 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d ** ^SQLite autom
34910 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 atically frees t
34920 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
34930 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 ted by .** sqlit
34940 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
34950 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 text() when the
34960 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 aggregate query
34970 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a concludes..**.**
34980 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
34990 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 eter must be a c
349a0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 opy of the.** [s
349b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c qlite3_context |
349c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f SQL function co
349d0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 ntext] that is t
349e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
349f0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 er.** to the xSt
34a00 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c ep or xFinal cal
34a10 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 lback routine th
34a20 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 at implements th
34a30 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 e aggregate.** f
34a40 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 unction..**.** T
34a50 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 his routine must
34a60 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
34a70 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
34a80 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 in which.** the
34a90 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
34aa0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
34ab0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 g..*/.void *sqli
34ac0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
34ad0 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f ntext(sqlite3_co
34ae0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 ntext*, int nByt
34af0 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 es);../*.** CAPI
34b00 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 3REF: User Data
34b10 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a For Functions.**
34b20 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
34b30 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e _context.**.** ^
34b40 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 The sqlite3_user
34b50 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 _data() interfac
34b60 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 e returns a copy
34b70 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 of.** the point
34b80 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 er that was the
34b90 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 pUserData parame
34ba0 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 ter (the 5th par
34bb0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 ameter).** of th
34bc0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 e [sqlite3_creat
34bd0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a e_function()].**
34be0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
34bf0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
34c00 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 )] routines that
34c10 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 originally.** r
34c20 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 egistered the ap
34c30 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 plication define
34c40 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a d function..**.*
34c50 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d * This routine m
34c60 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
34c70 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
34c80 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 ad in which.** t
34c90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
34ca0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
34cb0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 is running..*/.v
34cc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 oid *sqlite3_use
34cd0 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 r_data(sqlite3_c
34ce0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a ontext*);../*.**
34cf0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 CAPI3REF: Datab
34d00 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 ase Connection F
34d10 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 or Functions.**
34d20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
34d30 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 context.**.** ^T
34d40 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 he sqlite3_conte
34d50 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 xt_db_handle() i
34d60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
34d70 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 a copy of.** th
34d80 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 e pointer to the
34d90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
34da0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 ction] (the 1st
34db0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 parameter).** of
34dc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
34dd0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
34de0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
34df0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
34e00 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 16()] routines t
34e10 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a hat originally.*
34e20 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 * registered the
34e30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 application def
34e40 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a ined function..*
34e50 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 /.sqlite3 *sqlit
34e60 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 e3_context_db_ha
34e70 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e ndle(sqlite3_con
34e80 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 text*);../*.** C
34e90 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f API3REF: Functio
34ea0 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 n Auxiliary Data
34eb0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
34ec0 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a te3_context.**.*
34ed0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
34ee0 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 s may be used by
34ef0 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 (non-aggregate)
34f00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 SQL functions t
34f10 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d o.** associate m
34f20 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 etadata with arg
34f30 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 ument values. If
34f40 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 the same value
34f50 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 is passed to.**
34f60 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 multiple invocat
34f70 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
34f80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 SQL function du
34f90 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 ring query execu
34fa0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 tion, under.** s
34fb0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 ome circumstance
34fc0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 s the associated
34fd0 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 metadata may be
34fe0 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 preserved. An
34ff0 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 example.** of wh
35000 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 ere this might b
35010 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 e useful is in a
35020 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 regular-express
35030 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 ion matching.**
35040 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f function. The co
35050 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f mpiled version o
35060 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 f the regular ex
35070 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 pression can be
35080 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 stored as.** met
35090 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 adata associated
350a0 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72 with the patter
350b0 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 n string. .** T
350c0 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 hen as long as t
350d0 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e he pattern strin
350e0 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 g remains the sa
350f0 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 me,.** the compi
35100 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 led regular expr
35110 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 ession can be re
35120 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 used on multiple
35130 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 .** invocations
35140 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 of the same func
35150 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tion..**.** ^The
35160 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 sqlite3_get_aux
35170 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 data() interface
35180 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
35190 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 er to the metada
351a0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 ta.** associated
351b0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
351c0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 set_auxdata() fu
351d0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 nction with the
351e0 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 Nth argument.**
351f0 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 value to the app
35200 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
35210 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 function. ^If t
35220 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 here is no metad
35230 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ata.** associate
35240 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 d with the funct
35250 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 ion argument, th
35260 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 is sqlite3_get_a
35270 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
35280 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 ce.** returns a
35290 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
352a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
352b0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e _set_auxdata(C,N
352c0 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 ,P,X) interface
352d0 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 saves P as metad
352e0 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 ata for the N-th
352f0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 .** argument of
35300 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
35310 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
35320 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a . ^Subsequent.*
35330 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 * calls to sqlit
35340 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 e3_get_auxdata(C
35350 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f ,N) return P fro
35360 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e m the most recen
35370 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 t.** sqlite3_set
35380 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 _auxdata(C,N,P,X
35390 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 ) call if the me
353a0 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 tadata is still
353b0 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c valid or.** NULL
353c0 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 if the metadata
353d0 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 has been discar
353e0 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 ded..** ^After e
353f0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ach call to sqli
35400 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
35410 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 C,N,P,X) where X
35420 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a is not NULL,.**
35430 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 SQLite will inv
35440 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
35450 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 or function X wi
35460 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 th parameter P e
35470 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 xactly.** once,
35480 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 when the metadat
35490 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a a is discarded..
354a0 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 ** SQLite is fre
354b0 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 e to discard the
354c0 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 metadata at any
354d0 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 time, including
354e0 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 : <ul>.** <li> w
354f0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f hen the correspo
35500 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 nding function p
35510 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 arameter changes
35520 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 , or.** <li> whe
35530 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 n [sqlite3_reset
35540 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
35550 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 finalize()] is c
35560 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a alled for the.**
35570 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d SQL statem
35580 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 ent, or.** <li>
35590 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 when sqlite3_set
355a0 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e _auxdata() is in
355b0 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 voked again on t
355c0 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 he same paramete
355d0 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 r, or.** <li> du
355e0 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 ring the origina
355f0 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 l sqlite3_set_au
35600 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 xdata() call whe
35610 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 n a memory .**
35620 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 allocation e
35630 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 rror occurs. </u
35640 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 l>)^.**.** Note
35650 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 the last bullet
35660 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 in particular.
35670 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 The destructor X
35680 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f in .** sqlite3_
35690 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c set_auxdata(C,N,
356a0 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61 P,X) might be ca
356b0 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 lled immediately
356c0 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 , before the.**
356d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
356e0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
356f0 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 even returns. H
35700 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74 ence sqlite3_set
35710 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 _auxdata().** sh
35720 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e ould be called n
35730 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74 ear the end of t
35740 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c he function impl
35750 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 ementation and t
35760 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 he.** function i
35770 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 mplementation sh
35780 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e ould not make an
35790 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72 y use of P after
357a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f .** sqlite3_set_
357b0 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65 auxdata() has be
357c0 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a en called..**.**
357d0 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 ^(In practice,
357e0 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 metadata is pres
357f0 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 erved between fu
35800 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 nction calls for
35810 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 .** function par
35820 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 ameters that are
35830 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f compile-time co
35840 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 nstants, includi
35850 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 ng literal.** va
35860 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 lues and [parame
35870 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73 ters] and expres
35880 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 sions composed f
35890 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a rom the same.)^.
358a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
358b0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c ines must be cal
358c0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
358d0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
358e0 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e h.** the SQL fun
358f0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
35900 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
35910 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 e3_get_auxdata(s
35920 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
35930 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 int N);.void sq
35940 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
35950 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
35960 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a t*, int N, void*
35970 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a , void (*)(void*
35980 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ));.../*.** CAPI
35990 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 3REF: Constants
359a0 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c Defining Special
359b0 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 Destructor Beha
359c0 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 vior.**.** These
359d0 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c are special val
359e0 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 ues for the dest
359f0 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 ructor that is p
35a00 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a assed in as the.
35a10 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e ** final argumen
35a20 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 t to routines li
35a30 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 ke [sqlite3_resu
35a40 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 lt_blob()]. ^If
35a50 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a the destructor.
35a60 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 ** argument is S
35a70 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 QLITE_STATIC, it
35a80 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
35a90 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 content pointer
35aa0 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 is constant.** a
35ab0 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 nd will never ch
35ac0 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e ange. It does n
35ad0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 ot need to be de
35ae0 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a stroyed. ^The.*
35af0 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 * SQLITE_TRANSIE
35b00 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 NT value means t
35b10 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 hat the content
35b20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e will likely chan
35b30 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 ge in.** the nea
35b40 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 r future and tha
35b50 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 t SQLite should
35b60 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 make its own pri
35b70 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 vate copy of.**
35b80 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f the content befo
35b90 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a re returning..**
35ba0 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 .** The typedef
35bb0 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 is necessary to
35bc0 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 work around prob
35bd0 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a lems in certain.
35be0 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 ** C++ compilers
35bf0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 ..*/.typedef voi
35c00 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 d (*sqlite3_dest
35c10 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 ructor_type)(voi
35c20 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c d*);.#define SQL
35c30 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 ITE_STATIC
35c40 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 ((sqlite3_destru
35c50 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 ctor_type)0).#de
35c60 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e fine SQLITE_TRAN
35c70 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 SIENT ((sqlite
35c80 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 3_destructor_typ
35c90 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e)-1)../*.** CAP
35ca0 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 I3REF: Setting T
35cb0 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 he Result Of An
35cc0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20 SQL Function.**
35cd0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
35ce0 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 context.**.** Th
35cf0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
35d00 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 used by the xFu
35d10 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c nc or xFinal cal
35d20 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 lbacks that.** i
35d30 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e mplement SQL fun
35d40 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 ctions and aggre
35d50 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b gates. See.** [
35d60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
35d70 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b unction()] and [
35d80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
35d90 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 unction16()].**
35da0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 for additional i
35db0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
35dc0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
35dd0 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 s work very much
35de0 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d like the [param
35df0 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 eter binding] fa
35e00 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 mily of.** funct
35e10 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e ions used to bin
35e20 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 d values to host
35e30 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 parameters in p
35e40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
35e50 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 ts..** Refer to
35e60 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 the [SQL paramet
35e70 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f er] documentatio
35e80 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c n for additional
35e90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
35ea0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
35eb0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 _result_blob() i
35ec0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
35ed0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a e result from.**
35ee0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
35ef0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
35f00 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 to be the BLOB
35f10 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 whose content is
35f20 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 pointed.** to b
35f30 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 y the second par
35f40 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 ameter and which
35f50 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 is N bytes long
35f60 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a where N is the.
35f70 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 ** third paramet
35f80 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
35f90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
35fa0 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 roblob() interfa
35fb0 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 ces set the resu
35fc0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 lt of.** the app
35fd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
35fe0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
35ff0 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e a BLOB containin
36000 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 g all zero.** by
36010 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 tes and N bytes
36020 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e in size, where N
36030 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
36040 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
36050 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
36060 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f qlite3_result_do
36070 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 uble() interface
36080 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 sets the result
36090 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c from.** an appl
360a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
360b0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
360c0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
360d0 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a value specified.
360e0 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 ** by its 2nd ar
360f0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 gument..**.** ^T
36100 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
36110 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 t_error() and sq
36120 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
36130 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 or16() functions
36140 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d .** cause the im
36150 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 plemented SQL fu
36160 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 nction to throw
36170 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a an exception..**
36180 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 ^SQLite uses th
36190 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 e string pointed
361a0 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e to by the.** 2n
361b0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 d parameter of s
361c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
361d0 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ror() or sqlite3
361e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
361f0 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 ).** as the text
36200 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 of an error mes
36210 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 sage. ^SQLite i
36220 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 nterprets the er
36230 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 ror.** message s
36240 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 tring from sqlit
36250 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
36260 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c ) as UTF-8. ^SQL
36270 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 ite.** interpret
36280 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f s the string fro
36290 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 m sqlite3_result
362a0 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 _error16() as UT
362b0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a F-16 in native.*
362c0 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e * byte order. ^
362d0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 If the third par
362e0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
362f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
36300 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 .** or sqlite3_r
36310 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
36320 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e is negative then
36330 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 SQLite takes as
36340 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 the error.** me
36350 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 ssage all text u
36360 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 p through the fi
36370 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 rst zero charact
36380 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 er..** ^If the t
36390 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
363a0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 o sqlite3_result
363b0 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 _error() or.** s
363c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
363d0 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e ror16() is non-n
363e0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c egative then SQL
363f0 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d ite takes that m
36400 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f any.** bytes (no
36410 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 t characters) fr
36420 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d om the 2nd param
36430 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f eter as the erro
36440 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 r message..** ^T
36450 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
36460 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 t_error() and sq
36470 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
36480 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e or16().** routin
36490 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 es make a privat
364a0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 e copy of the er
364b0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 ror message text
364c0 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 before.** they
364d0 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 return. Hence,
364e0 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 the calling func
364f0 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 tion can dealloc
36500 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 ate or.** modify
36510 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 the text after
36520 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 they return with
36530 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 out harm..** ^Th
36540 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
36550 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 _error_code() fu
36560 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 nction changes t
36570 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a he error code.**
36580 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c returned by SQL
36590 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 ite as a result
365a0 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 of an error in a
365b0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 function. ^By
365c0 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 default,.** the
365d0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 error code is SQ
365e0 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 LITE_ERROR. ^A
365f0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 subsequent call
36600 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
36610 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 t_error().** or
36620 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
36630 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 rror16() resets
36640 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 the error code t
36650 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a o SQLITE_ERROR..
36660 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
36670 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
36680 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 toobig() interfa
36690 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 ce causes SQLite
366a0 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 to throw an.**
366b0 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 error indicating
366c0 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f that a string o
366d0 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f r BLOB is too lo
366e0 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e ng to represent.
366f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
36700 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
36710 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 _nomem() interfa
36720 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 ce causes SQLite
36730 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 to throw an.**
36740 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 error indicating
36750 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 that a memory a
36760 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 llocation failed
36770 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
36780 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 ite3_result_int(
36790 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
367a0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
367b0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c e.** of the appl
367c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
367d0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 function to be t
367e0 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 he 32-bit signed
367f0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 integer.** valu
36800 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 e given in the 2
36810 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 nd argument..**
36820 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
36830 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 ult_int64() inte
36840 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
36850 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
36860 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
36870 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
36880 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d on to be the 64-
36890 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
368a0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 er.** value give
368b0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 n in the 2nd arg
368c0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ument..**.** ^Th
368d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
368e0 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 _null() interfac
368f0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 e sets the retur
36900 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 n value.** of th
36910 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
36920 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
36930 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a o be NULL..**.**
36940 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
36950 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c sult_text(), sql
36960 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
36970 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 16(),.** sqlite3
36980 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 _result_text16le
36990 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f (), and sqlite3_
369a0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 result_text16be(
369b0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
369c0 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 set the return v
369d0 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c alue of the appl
369e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
369f0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a function to be.*
36a00 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 * a text string
36a10 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 which is represe
36a20 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 nted as UTF-8, U
36a30 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 TF-16 native byt
36a40 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d e order,.** UTF-
36a50 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 16 little endian
36a60 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 , or UTF-16 big
36a70 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 endian, respecti
36a80 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 vely..** ^The sq
36a90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
36aa0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 t64() interface
36ab0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 sets the return
36ac0 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 value of an.** a
36ad0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
36ae0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
36af0 65 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 e a text string
36b00 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a in an encoding.*
36b10 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 * specified by t
36b20 68 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c 61 he fifth (and la
36b30 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20 77 st) parameter, w
36b40 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 hich must be one
36b50 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 .** of [SQLITE_U
36b60 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 TF8], [SQLITE_UT
36b70 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 F16], [SQLITE_UT
36b80 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 F16BE], or [SQLI
36b90 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 TE_UTF16LE]..**
36ba0 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 ^SQLite takes th
36bb0 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 e text result fr
36bc0 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 om the applicati
36bd0 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 on from.** the 2
36be0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 nd parameter of
36bf0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
36c00 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
36c10 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ces..** ^If the
36c20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
36c30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
36c40 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
36c50 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 aces.** is negat
36c60 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ive, then SQLite
36c70 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 takes result te
36c80 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 xt from the 2nd
36c90 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 parameter.** thr
36ca0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a ough the first z
36cb0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ero character..*
36cc0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 * ^If the 3rd pa
36cd0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
36ce0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
36cf0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
36d00 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 * is non-negativ
36d10 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 e, then as many
36d20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 bytes (not chara
36d30 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 cters) of the te
36d40 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f xt.** pointed to
36d50 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 by the 2nd para
36d60 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 meter are taken
36d70 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 as the applicati
36d80 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 on-defined.** fu
36d90 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 nction result.
36da0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d If the 3rd param
36db0 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 eter is non-nega
36dc0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a tive, then it.**
36dd0 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 must be the byt
36de0 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 e offset into th
36df0 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 e string where t
36e00 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f he NUL terminato
36e10 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 r would.** appea
36e20 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 r if the string
36e30 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e where NUL termin
36e40 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 ated. If any NU
36e50 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 L characters occ
36e60 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 ur.** in the str
36e70 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 ing at a byte of
36e80 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 fset that is les
36e90 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 s than the value
36ea0 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 of the 3rd.** p
36eb0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 arameter, then t
36ec0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 he resulting str
36ed0 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e ing will contain
36ee0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 embedded NULs a
36ef0 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 nd the.** result
36f00 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 of expressions
36f10 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 operating on str
36f20 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 ings with embedd
36f30 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 ed NULs is undef
36f40 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ined..** ^If the
36f50 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
36f60 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
36f70 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
36f80 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 faces.** or sqli
36f90 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
36fa0 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f is a non-NULL po
36fb0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 inter, then SQLi
36fc0 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a te calls that.**
36fd0 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 function as the
36fe0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 destructor on t
36ff0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 he text or BLOB
37000 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 result when it h
37010 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 as.** finished u
37020 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 sing that result
37030 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 ..** ^If the 4th
37040 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
37050 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
37060 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
37070 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 s or to.** sqlit
37080 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 e3_result_blob i
37090 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f s the special co
370a0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 nstant SQLITE_ST
370b0 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 ATIC, then SQLit
370c0 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 e.** assumes tha
370d0 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c t the text or BL
370e0 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 OB result is in
370f0 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 constant space a
37100 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 nd does not.** c
37110 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 opy the content
37120 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 of the parameter
37130 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 nor call a dest
37140 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f ructor on the co
37150 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 ntent.** when it
37160 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 has finished us
37170 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e ing that result.
37180 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 .** ^If the 4th
37190 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
371a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
371b0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
371c0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 .** or sqlite3_r
371d0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 esult_blob is th
371e0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 e special consta
371f0 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 nt SQLITE_TRANSI
37200 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 ENT.** then SQLi
37210 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 te makes a copy
37220 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e of the result in
37230 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 to space obtaine
37240 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b d from.** from [
37250 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
37260 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 ] before it retu
37270 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rns..**.** ^The
37280 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
37290 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 alue() interface
372a0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 sets the result
372b0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 of.** the appli
372c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
372d0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 unction to be a
372e0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b copy of the.** [
372f0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
37300 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
37310 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 t specified by t
37320 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
37330 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 . ^The.** sqlit
37340 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
37350 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 ) interface make
37360 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
37370 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a [sqlite3_value].
37380 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b ** so that the [
37390 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 sqlite3_value] s
373a0 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 pecified in the
373b0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 parameter may ch
373c0 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 ange or.** be de
373d0 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 allocated after
373e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
373f0 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 alue() returns w
37400 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 ithout harm..**
37410 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 ^A [protected sq
37420 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
37430 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 ect may always b
37440 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a e used where an.
37450 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 ** [unprotected
37460 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
37470 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 bject is require
37480 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 d, so either.**
37490 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 kind of [sqlite3
374a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 _value] object c
374b0 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 an be used with
374c0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a this interface..
374d0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 **.** If these r
374e0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c outines are call
374f0 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 ed from within t
37500 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 he different thr
37510 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 ead.** than the
37520 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 one containing t
37530 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
37540 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
37550 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a that received.**
37560 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
37570 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 ntext] pointer,
37580 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
37590 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f undefined..*/.vo
375a0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
375b0 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 t_blob(sqlite3_c
375c0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
375d0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 oid*, int, void(
375e0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
375f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37600 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 63 blob64(sqlite3_c
37610 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f ontext*,const vo
37620 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 id*,.
37630 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
37640 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76 sqlite3_uint64,v
37650 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
37660 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
37670 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 ult_double(sqlit
37680 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 e3_context*, dou
37690 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 ble);.void sqlit
376a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
376b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
376c0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 , const char*, i
376d0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 nt);.void sqlite
376e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
376f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
37700 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
37710 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
37720 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
37730 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 toobig(sqlite3_c
37740 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 ontext*);.void s
37750 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
37760 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 ror_nomem(sqlite
37770 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 3_context*);.voi
37780 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
37790 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 _error_code(sqli
377a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
377b0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
377c0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 _result_int(sqli
377d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
377e0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
377f0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 _result_int64(sq
37800 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
37810 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
37820 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
37830 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 ult_null(sqlite3
37840 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 _context*);.void
37850 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37860 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
37870 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 text*, const cha
37880 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 r*, int, void(*)
37890 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
378a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
378b0 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e xt64(sqlite3_con
378c0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 text*, const cha
378d0 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 r*,sqlite3_uint6
378e0 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 4,.
378f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f vo
37900 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e id(*)(void*), un
37910 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f signed char enco
37920 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69 ding);.void sqli
37930 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
37940 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 6(sqlite3_contex
37950 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
37960 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
37970 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 id*));.void sqli
37980 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
37990 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 6le(sqlite3_cont
379a0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
379b0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 *, int,void(*)(v
379c0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c oid*));.void sql
379d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
379e0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 16be(sqlite3_con
379f0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
37a00 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 d*, int,void(*)(
37a10 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 void*));.void sq
37a20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
37a30 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ue(sqlite3_conte
37a40 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c xt*, sqlite3_val
37a50 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 ue*);.void sqlit
37a60 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c e3_result_zerobl
37a70 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ob(sqlite3_conte
37a80 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a xt*, int n);../*
37a90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
37aa0 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 fine New Collati
37ab0 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 20 ng Sequences.**
37ac0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
37ad0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e **.** ^These fun
37ae0 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f ctions add, remo
37af0 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 ve, or modify a
37b00 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f [collation] asso
37b10 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 ciated.** with t
37b20 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
37b30 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
37b40 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
37b50 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
37b60 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 ^The name of the
37b70 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 collation is a
37b80 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 UTF-8 string.**
37b90 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
37ba0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 te_collation() a
37bb0 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nd sqlite3_creat
37bc0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
37bd0 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 .** and a UTF-16
37be0 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 string in nativ
37bf0 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 e byte order for
37c00 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
37c10 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a collation16()..*
37c20 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d * ^Collation nam
37c30 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 es that compare
37c40 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 equal according
37c50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e to [sqlite3_strn
37c60 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 icmp()] are.** c
37c70 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 onsidered to be
37c80 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a the same name..*
37c90 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 *.** ^(The third
37ca0 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 argument (eText
37cb0 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 Rep) must be one
37cc0 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 of the constant
37cd0 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c s:.** <ul>.** <l
37ce0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d i> [SQLITE_UTF8]
37cf0 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ,.** <li> [SQLIT
37d00 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c E_UTF16LE],.** <
37d10 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 li> [SQLITE_UTF1
37d20 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 6BE],.** <li> [S
37d30 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 QLITE_UTF16], or
37d40 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
37d50 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e _UTF16_ALIGNED].
37d60 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e .** </ul>)^.** ^
37d70 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 The eTextRep arg
37d80 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 ument determines
37d90 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 the encoding of
37da0 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a strings passed.
37db0 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 ** to the collat
37dc0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c ing function cal
37dd0 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b lback, xCallback
37de0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ..** ^The [SQLIT
37df0 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 E_UTF16] and [SQ
37e00 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e LITE_UTF16_ALIGN
37e10 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 ED] values for e
37e20 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 TextRep.** force
37e30 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 strings to be U
37e40 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 TF16 with native
37e50 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 byte order..**
37e60 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 ^The [SQLITE_UTF
37e70 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 16_ALIGNED] valu
37e80 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 e for eTextRep f
37e90 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f orces strings to
37ea0 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 begin.** on an
37eb0 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 even byte addres
37ec0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f s..**.** ^The fo
37ed0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 urth argument, p
37ee0 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 Arg, is an appli
37ef0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
37f00 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 ter that is pass
37f10 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 ed.** through as
37f20 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
37f30 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 ent to the colla
37f40 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ting function ca
37f50 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 llback..**.** ^T
37f60 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
37f70 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 t, xCallback, is
37f80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
37f90 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 e collating func
37fa0 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 tion..** ^Multip
37fb0 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e le collating fun
37fc0 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 ctions can be re
37fd0 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 gistered using t
37fe0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 he same name but
37ff0 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 .** with differe
38000 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61 nt eTextRep para
38010 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 meters and SQLit
38020 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 e will use which
38030 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ever.** function
38040 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 requires the le
38050 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 ast amount of da
38060 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f ta transformatio
38070 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 n..** ^If the xC
38080 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 allback argument
38090 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 is NULL then th
380a0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 e collating func
380b0 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 tion is.** delet
380c0 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 ed. ^When all c
380d0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
380e0 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 ns having the sa
380f0 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 me name are dele
38100 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c ted,.** that col
38110 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e lation is no lon
38120 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a ger usable..**.*
38130 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 * ^The collating
38140 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 function callba
38150 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 ck is invoked wi
38160 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 th a copy of the
38170 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 pArg .** applic
38180 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 ation data point
38190 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 er and with two
381a0 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 strings in the e
381b0 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 ncoding specifie
381c0 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 d.** by the eTex
381d0 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 tRep argument.
381e0 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 The collating fu
381f0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 nction must retu
38200 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 rn an.** integer
38210 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 that is negativ
38220 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 e, zero, or posi
38230 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 tive.** if the f
38240 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c irst string is l
38250 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 ess than, equal
38260 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 to, or greater t
38270 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a han the second,.
38280 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e ** respectively.
38290 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 A collating fu
382a0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 nction must alwa
382b0 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 ys return the sa
382c0 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 me answer.** giv
382d0 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 en the same inpu
382e0 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d ts. If two or m
382f0 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 ore collating fu
38300 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 nctions are regi
38310 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 stered.** to the
38320 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 same collation
38330 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 name (using diff
38340 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 erent eTextRep v
38350 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a alues) then all.
38360 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 ** must give an
38370 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 equivalent answe
38380 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 r when invoked w
38390 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 ith equivalent s
383a0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 trings..** The c
383b0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
383c0 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 n must obey the
383d0 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 following proper
383e0 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 ties for all.**
383f0 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e strings A, B, an
38400 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a d C:.**.** <ol>.
38410 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 ** <li> If A==B
38420 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c then B==A..** <l
38430 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 i> If A==B and B
38440 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a ==C then A==C..*
38450 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 * <li> If A<B
38460 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a THEN B>A..**
38470 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 <li> If A<B
38480 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 and B<C then
38490 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e A<C..** </ol>
384a0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c .**.** If a coll
384b0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 ating function f
384c0 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 ails any of the
384d0 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 above constraint
384e0 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f s and that.** co
384f0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
38500 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20 is registered
38510 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 and used, then t
38520 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 he behavior of S
38530 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 QLite.** is unde
38540 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
38550 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 e sqlite3_create
38560 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 _collation_v2()
38570 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
38580 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
38590 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 ion().** with th
385a0 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 e addition that
385b0 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c the xDestroy cal
385c0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
385d0 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a on pArg when.**
385e0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 the collating f
385f0 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 unction is delet
38600 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e ed..** ^Collatin
38610 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 g functions are
38620 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 deleted when the
38630 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e y are overridden
38640 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c by later.** cal
38650 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 ls to the collat
38660 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e ion creation fun
38670 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 ctions or when t
38680 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 he.** [database
38690 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 connection] is c
386a0 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c losed using [sql
386b0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a ite3_close()]..*
386c0 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 *.** ^The xDestr
386d0 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c oy callback is <
386e0 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 u>not</u> called
386f0 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 if the .** sqli
38700 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
38710 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 tion_v2() functi
38720 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 on fails. Appli
38730 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 cations that inv
38740 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 oke.** sqlite3_c
38750 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
38760 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d v2() with a non-
38770 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 NULL xDestroy ar
38780 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a gument should .*
38790 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 * check the retu
387a0 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 rn code and disp
387b0 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 ose of the appli
387c0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
387d0 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 ter.** themselve
387e0 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 s rather than ex
387f0 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 pecting SQLite t
38800 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 o deal with it f
38810 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 or them..** This
38820 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 is different fr
38830 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 om every other S
38840 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
38850 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 The inconsiste
3