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 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 _IOERR_VNODE
55b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
55c0: 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 _IOERR | (27<<8)
55d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
55e0: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 _LOCKED_SHAREDCA
55f0: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 CHE (SQLITE
5600: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 _LOCKED | (1<<8
5610: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5620: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 E_BUSY_RECOVERY
5630: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5640: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c E_BUSY | (1<<
5650: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5660: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 TE_BUSY_SNAPSHOT
5670: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
5680: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c TE_BUSY | (2<
5690: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
56a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 ITE_CANTOPEN_NOT
56b0: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c EMPDIR (SQL
56c0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
56d0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
56e0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 QLITE_CANTOPEN_I
56f0: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53 SDIR (S
5700: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c QLITE_CANTOPEN |
5710: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
5720: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
5730: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 _FULLPATH
5740: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e (SQLITE_CANTOPEN
5750: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 | (3<<8)).#defi
5760: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 ne SQLITE_CANTOP
5770: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 EN_CONVPATH
5780: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 (SQLITE_CANTOP
5790: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 EN | (4<<8)).#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 fine SQLITE_CORR
57b0: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 UPT_VTAB
57c0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 (SQLITE_CORR
57d0: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 UPT | (1<<8)).#d
57e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
57f0: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 DONLY_RECOVERY
5800: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
5810: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a DONLY | (1<<8)).
5820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
5830: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b EADONLY_CANTLOCK
5840: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 (SQLITE_R
5850: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 EADONLY | (2<<8)
5860: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5870: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 _READONLY_ROLLBA
5880: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 CK (SQLITE
5890: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c _READONLY | (3<<
58a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
58b0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f TE_READONLY_DBMO
58c0: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 VED (SQLI
58d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 TE_READONLY | (4
58e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
58f0: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 LITE_ABORT_ROLLB
5900: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 ACK (SQ
5910: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c LITE_ABORT | (2<
5920: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5930: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 ITE_CONSTRAINT_C
5940: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c HECK (SQL
5950: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5960: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
5970: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5980: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 NT_COMMITHOOK
5990: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
59a0: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 NT | (2<<8)).#de
59b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
59c0: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 TRAINT_FOREIGNKE
59d0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 Y (SQLITE_CONS
59e0: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 TRAINT | (3<<8))
59f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5a00: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 CONSTRAINT_FUNCT
5a10: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f ION (SQLITE_
5a20: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c CONSTRAINT | (4<
5a30: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5a40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e ITE_CONSTRAINT_N
5a50: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c OTNULL (SQL
5a60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5a70: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (5<<8)).#define
5a80: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5a90: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 NT_PRIMARYKEY
5aa0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5ab0: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 NT | (6<<8)).#de
5ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5ad0: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 TRAINT_TRIGGER
5ae0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
5af0: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 TRAINT | (7<<8))
5b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5b10: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 CONSTRAINT_UNIQU
5b20: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f E (SQLITE_
5b30: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c CONSTRAINT | (8<
5b40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5b50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 ITE_CONSTRAINT_V
5b60: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c TAB (SQL
5b70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5b80: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (9<<8)).#define
5b90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5ba0: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 NT_ROWID
5bb0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5bc0: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 NT |(10<<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 57 41 4c 20 20 CE_RECOVER_WAL
5bf0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 (SQLITE_NOTI
5c00: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 CE | (1<<8)).#de
5c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 fine SQLITE_NOTI
5c20: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 CE_RECOVER_ROLLB
5c30: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 ACK (SQLITE_NOTI
5c40: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 CE | (2<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e fine SQLITE_WARN
5c60: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 ING_AUTOINDEX
5c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e (SQLITE_WARN
5c80: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 ING | (1<<8)).#d
5c90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 efine SQLITE_AUT
5ca0: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 H_USER
5cb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 (SQLITE_AUT
5cc0: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a H | (1<<8))../*.
5cd0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 ** CAPI3REF: Fla
5ce0: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e gs For File Open
5cf0: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a Operations.**.*
5d00: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 * These bit valu
5d10: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 es are intended
5d20: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a for use in the.*
5d30: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 * 3rd parameter
5d40: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
5d50: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 open_v2()] inter
5d60: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 face and.** in t
5d70: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
5d80: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
5d90: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 _vfs.xOpen] meth
5da0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 od..*/.#define S
5db0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
5dc0: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 NLY 0x00
5dd0: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 000001 /* Ok fo
5de0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5df0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5e00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
5e10: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 RITE 0x00
5e20: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 000002 /* Ok fo
5e30: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5e40: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5e50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
5e60: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 E 0x00
5e70: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 000004 /* Ok fo
5e80: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5e90: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5ea0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
5eb0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 EONCLOSE 0x00
5ec0: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 000008 /* 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 45 58 43 4c 55 QLITE_OPEN_EXCLU
5ef0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 SIVE 0x00
5f00: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 000010 /* 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 41 55 54 4f 50 QLITE_OPEN_AUTOP
5f30: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 ROXY 0x00
5f40: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 000020 /* VFS o
5f50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5f60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 QLITE_OPEN_URI
5f70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
5f80: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 000040 /* Ok fo
5f90: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5fa0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5fb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 QLITE_OPEN_MEMOR
5fc0: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 Y 0x00
5fd0: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 000080 /* Ok fo
5fe0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5ff0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
6000: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
6010: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
6020: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 000100 /* 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 45 4d 50 5f QLITE_OPEN_TEMP_
6050: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
6060: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 000200 /* VFS o
6070: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
6080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 QLITE_OPEN_TRANS
6090: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 IENT_DB 0x00
60a0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 000400 /* 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 4d 41 49 4e 5f QLITE_OPEN_MAIN_
60d0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
60e0: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 000800 /* 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 54 45 4d 50 5f QLITE_OPEN_TEMP_
6110: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
6120: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 001000 /* 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 53 55 42 4a 4f QLITE_OPEN_SUBJO
6150: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 URNAL 0x00
6160: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 002000 /* 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 4d 41 53 54 45 QLITE_OPEN_MASTE
6190: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 R_JOURNAL 0x00
61a0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 004000 /* VFS o
61b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
61c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
61d0: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 EX 0x00
61e0: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 008000 /* Ok fo
61f0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
6200: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
6210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
6220: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 UTEX 0x00
6230: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 010000 /* Ok fo
6240: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
6250: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
6260: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
6270: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 DCACHE 0x00
6280: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 020000 /* Ok fo
6290: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
62a0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
62b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
62c0: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 TECACHE 0x00
62d0: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 040000 /* Ok fo
62e0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
62f0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
6300: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 QLITE_OPEN_WAL
6310: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6320: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 080000 /* VFS o
6330: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 nly */../* Reser
6340: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 ved:
6350: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6360: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 0F00000 */../*.*
6370: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 * CAPI3REF: Devi
6380: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 ce Characteristi
6390: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 cs.**.** The xDe
63a0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
63b0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 ics method of th
63c0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
63d0: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 thods].** object
63e0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 returns an inte
63f0: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 ger which is a v
6400: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a ector of these.*
6410: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 * bit values exp
6420: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 ressing I/O char
6430: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 acteristics of t
6440: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a he mass storage.
6450: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 ** device that h
6460: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 olds the file th
6470: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
6480: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 io_methods].** r
6490: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 efers to..**.**
64a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
64b0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
64c0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
64d0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
64e0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
64f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
6500: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
6510: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
6520: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
6530: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
6540: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
6550: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
6560: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
6570: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
6580: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
6590: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
65a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
65b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
65c0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
65d0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
65e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
65f0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
6600: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
6610: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
6620: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
6630: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
6640: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
6650: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
6660: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
6670: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
6680: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
6690: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
66a0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
66b0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
66c0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
66d0: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 ite(). The SQLI
66e0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
66f0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f FE_OVERWRITE pro
6700: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
6710: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 .** after reboot
6720: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 following a cra
6730: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 sh or power loss
6740: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 , the only bytes
6750: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 in a.** file th
6760: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 at were written
6770: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 at the applicati
6780: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 on level might h
6790: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 ave changed.** a
67a0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 nd that adjacent
67b0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 bytes, even byt
67c0: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 es within the sa
67d0: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a me sector are.**
67e0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 guaranteed to b
67f0: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 e unchanged. Th
6800: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 e SQLITE_IOCAP_U
6810: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f NDELETABLE_WHEN_
6820: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 OPEN.** flag ind
6830: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c icate that a fil
6840: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 e cannot be dele
6850: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 ted when open.
6860: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f The.** SQLITE_IO
6870: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c CAP_IMMUTABLE fl
6880: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 ag indicates tha
6890: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e t the file is on
68a0: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 .** read-only me
68b0: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 dia and cannot b
68c0: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 e changed even b
68d0: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 y processes with
68e0: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 .** elevated pri
68f0: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 vileges..*/.#def
6900: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6910: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 _ATOMIC
6920: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6930: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 01.#define SQLIT
6940: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
6950: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 2 0
6960: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e x00000002.#defin
6970: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6980: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 TOMIC1K
6990: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
69a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
69b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 IOCAP_ATOMIC2K
69c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
69d0: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 0000008.#define
69e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
69f0: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 MIC4K
6a00: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 0x00000010.#
6a10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6a20: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 CAP_ATOMIC8K
6a30: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6a40: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 00020.#define SQ
6a50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6a60: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 C16K
6a70: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 0x00000040.#de
6a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6a90: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 P_ATOMIC32K
6aa0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6ab0: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 080.#define SQLI
6ac0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 TE_IOCAP_ATOMIC6
6ad0: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 4K
6ae0: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 0x00000100.#defi
6af0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6b00: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 SAFE_APPEND
6b10: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 0x0000020
6b20: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
6b30: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
6b40: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 L 0x
6b50: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 00000400.#define
6b60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e SQLITE_IOCAP_UN
6b70: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f DELETABLE_WHEN_O
6b80: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a PEN 0x00000800.
6b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6ba0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f OCAP_POWERSAFE_O
6bb0: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 VERWRITE 0x00
6bc0: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 001000.#define S
6bd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 QLITE_IOCAP_IMMU
6be0: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 TABLE
6bf0: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 0x00002000../
6c00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
6c10: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 ile Locking Leve
6c20: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 ls.**.** SQLite
6c30: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 uses one of thes
6c40: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
6c50: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a as the second.*
6c60: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 * argument to ca
6c70: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 lls it makes to
6c80: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 the xLock() and
6c90: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 xUnlock() method
6ca0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 s.** of an [sqli
6cb0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
6cc0: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 object..*/.#defi
6cd0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e ne SQLITE_LOCK_N
6ce0: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 ONE 0.#
6cf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
6d00: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 CK_SHARED
6d10: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
6d20: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 E_LOCK_RESERVED
6d30: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
6d40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
6d50: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 NG 3.#defi
6d60: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 ne SQLITE_LOCK_E
6d70: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a XCLUSIVE 4..
6d80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
6d90: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 Synchronization
6da0: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a Type Flags.**.**
6db0: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 When SQLite inv
6dc0: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 okes the xSync()
6dd0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a method of an.**
6de0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
6df0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 hods] object it
6e00: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 uses a combinati
6e10: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 on of.** these i
6e20: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 nteger values as
6e30: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
6e40: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e ment..**.** When
6e50: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 the SQLITE_SYNC
6e60: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 _DATAONLY flag i
6e70: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 s used, it means
6e80: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e that the.** syn
6e90: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 c operation only
6ea0: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 needs to flush
6eb0: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f data to mass sto
6ec0: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 rage. Inode.**
6ed0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 information need
6ee0: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e not be flushed.
6ef0: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f If the lower fo
6f00: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 ur bits of the f
6f10: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c lag.** equal SQL
6f20: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c ITE_SYNC_NORMAL,
6f30: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 that means to u
6f40: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 se normal fsync(
6f50: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 ) semantics..**
6f60: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 If the lower fou
6f70: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c r bits equal SQL
6f80: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 ITE_SYNC_FULL, t
6f90: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 hat means.** to
6fa0: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 use Mac OS X sty
6fb0: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 le fullsync inst
6fc0: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a ead of fsync()..
6fd0: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e **.** Do not con
6fe0: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f fuse the SQLITE_
6ff0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
7000: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
7010: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 flags.** with t
7020: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 he [PRAGMA synch
7030: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 ronous]=NORMAL a
7040: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 nd [PRAGMA synch
7050: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 ronous]=FULL.**
7060: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b settings. The [
7070: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 synchronous prag
7080: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 ma] determines w
7090: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 hen calls to the
70a0: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 .** xSync VFS me
70b0: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 thod occur and a
70c0: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 pplies uniformly
70d0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 across all plat
70e0: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 forms..** The SQ
70f0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
7100: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 and SQLITE_SYNC
7110: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 _FULL flags dete
7120: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 rmine how.** ene
7130: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f rgetic or rigoro
7140: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 us or forceful t
7150: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f he sync operatio
7160: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e ns are and.** on
7170: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 ly make a differ
7180: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 ence on Mac OSX
7190: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 for the default
71a0: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 SQLite code..**
71b0: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 (Third-party VFS
71c0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
71d0: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 might also make
71e0: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e the distinction
71f0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 .** between SQLI
7200: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 TE_SYNC_NORMAL a
7210: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 nd SQLITE_SYNC_F
7220: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 ULL, but among t
7230: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 he.** operating
7240: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 systems natively
7250: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 supported by SQ
7260: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f Lite, only Mac O
7270: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 SX.** cares abou
7280: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 t the difference
7290: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 .).*/.#define SQ
72a0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
72b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 0x00002.
72c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
72d0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 YNC_FULL
72e0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 0x00003.#defin
72f0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
7300: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 TAONLY 0x00
7310: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 010../*.** CAPI3
7320: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
7330: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 e Open File Hand
7340: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c le.**.** An [sql
7350: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
7360: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 t represents an
7370: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 open file in the
7380: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 .** [sqlite3_vf
7390: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 s | OS interface
73a0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 layer]. Indivi
73b0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 dual OS interfac
73c0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
73d0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e ions will.** wan
73e0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 t to subclass th
73f0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 is object by app
7400: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 ending additiona
7410: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 l fields.** for
7420: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 their own use.
7430: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 The pMethods ent
7440: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ry is a pointer
7450: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 to an.** [sqlite
7460: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
7470: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
7480: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 s methods for pe
7490: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 rforming.** I/O
74a0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 operations on th
74b0: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a e open file..*/.
74c0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
74d0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 qlite3_file sqli
74e0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 te3_file;.struct
74f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a sqlite3_file {.
7500: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 const struct s
7510: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
7520: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a s *pMethods; /*
7530: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 Methods for an
7540: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a open file */.};.
7550: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
7560: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 OS Interface Fi
7570: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f le Virtual Metho
7580: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 ds Object.**.**
7590: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 Every file opene
75a0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
75b0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 3_vfs.xOpen] met
75c0: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e hod populates an
75d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
75e0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d e] object (or, m
75f0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 ore commonly, a
7600: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a subclass of the.
7610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
7620: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 ] object) with a
7630: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
7640: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
7650: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 object..** This
7660: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
7670: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 he methods used
7680: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
7690: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a us operations.**
76a0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 against the ope
76b0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 n file represent
76c0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
76d0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e e3_file] object.
76e0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 .**.** If the [s
76f0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
7700: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 ] method sets th
7710: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
7720: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 Methods element
7730: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c .** to a non-NUL
7740: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
7750: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d the sqlite3_io_m
7760: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 ethods.xClose me
7770: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 thod.** may be i
7780: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 nvoked even if t
7790: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
77a0: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 xOpen] reported
77b0: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 that it failed.
77c0: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 The.** only way
77d0: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 to prevent a ca
77e0: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c ll to xClose fol
77f0: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 lowing a failed
7800: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
7810: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 en].** is for th
7820: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
7830: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 Open] to set the
7840: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
7850: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a ethods element.*
7860: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a * to NULL..**.**
7870: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d The flags argum
7880: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 ent to xSync may
7890: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 be one of [SQLI
78a0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 TE_SYNC_NORMAL]
78b0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 or.** [SQLITE_SY
78c0: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 NC_FULL]. The f
78d0: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 irst choice is t
78e0: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 he normal fsync(
78f0: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 )..** The second
7900: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 choice is a Mac
7910: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c OS X style full
7920: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 sync. The [SQLI
7930: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
7940: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 ].** flag may be
7950: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 ORed in to indi
7960: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 cate that only t
7970: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 he data of the f
7980: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 ile.** and not i
7990: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 ts inode needs t
79a0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a o be synced..**.
79b0: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 ** The integer v
79c0: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 alues to xLock()
79d0: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 and xUnlock() a
79e0: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c re one of.** <ul
79f0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
7a00: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a E_LOCK_NONE],.**
7a10: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
7a20: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c CK_SHARED],.** <
7a30: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
7a40: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c _RESERVED],.** <
7a50: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
7a60: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a _PENDING], or.**
7a70: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
7a80: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a CK_EXCLUSIVE]..*
7a90: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b * </ul>.** xLock
7aa0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 () increases the
7ab0: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 lock. xUnlock()
7ac0: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c decreases the l
7ad0: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 ock..** The xChe
7ae0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 ckReservedLock()
7af0: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 method checks w
7b00: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 hether any datab
7b10: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a ase connection,.
7b20: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 ** either in thi
7b30: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 s process or in
7b40: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 some other proce
7b50: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 ss, is holding a
7b60: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 RESERVED,.** PE
7b70: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 NDING, or EXCLUS
7b80: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 IVE lock on the
7b90: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e file. It return
7ba0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 s true.** if suc
7bb0: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 h a lock exists
7bc0: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 and false otherw
7bd0: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ise..**.** The x
7be0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 FileControl() me
7bf0: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 thod is a generi
7c00: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 c interface that
7c10: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a allows custom.*
7c20: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 * VFS implementa
7c30: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c tions to directl
7c40: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 y control an ope
7c50: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 n file using the
7c60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
7c70: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 e_control()] int
7c80: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 erface. The sec
7c90: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e ond "op" argumen
7ca0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 t is an.** integ
7cb0: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 er opcode. The
7cc0: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
7cd0: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e s a generic poin
7ce0: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a ter intended to.
7cf0: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 ** point to a st
7d00: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 ructure that may
7d10: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e contain argumen
7d20: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 ts or space in w
7d30: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 hich to.** write
7d40: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 return values.
7d50: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 Potential uses
7d60: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c for xFileControl
7d70: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 () might be.** f
7d80: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 unctions to enab
7d90: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b le blocking lock
7da0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c s with timeouts,
7db0: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a to change the.*
7dc0: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 * locking strate
7dd0: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 gy (for example
7de0: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 to use dot-file
7df0: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 locks), to inqui
7e00: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 re.** about the
7e10: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b status of a lock
7e20: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 , or to break st
7e30: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 ale locks. The
7e40: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 SQLite.** core r
7e50: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f eserves all opco
7e60: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 des less than 10
7e70: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 0 for its own us
7e80: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f e..** A [file co
7e90: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 ntrol opcodes |
7ea0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d list of opcodes]
7eb0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 less than 100 i
7ec0: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 s available..**
7ed0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
7ee0: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f t define a custo
7ef0: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d m xFileControl m
7f00: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 ethod should use
7f10: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 opcodes.** grea
7f20: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 ter than 100 to
7f30: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e avoid conflicts.
7f40: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 VFS implementa
7f50: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 tions should.**
7f60: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e return [SQLITE_N
7f70: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c OTFOUND] for fil
7f80: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 e control opcode
7f90: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e s that they do n
7fa0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e ot.** recognize.
7fb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 .**.** The xSect
7fc0: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 orSize() method
7fd0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 returns the sect
7fe0: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a or size of the.*
7ff0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e * device that un
8000: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 derlies the file
8010: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 . The sector si
8020: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e ze is the.** min
8030: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 imum write that
8040: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 can be performed
8050: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 without disturb
8060: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 ing.** other byt
8070: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 es in the file.
8080: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 The xDeviceChar
8090: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a acteristics().**
80a0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
80b0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 a bit vector des
80c0: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 cribing behavior
80d0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 s of the.** unde
80e0: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a rlying device:.*
80f0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
8100: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
8110: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 ATOMIC].** <li>
8120: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
8130: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e OMIC512].** <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 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC1K].** <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 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC2K].** <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 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC4K].** <li>
81a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
81b0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC8K].** <li>
81c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
81d0: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC16K].** <li
81e0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
81f0: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c ATOMIC32K].** <l
8200: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
8210: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c _ATOMIC64K].** <
8220: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
8230: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a P_SAFE_APPEND].*
8240: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
8250: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d OCAP_SEQUENTIAL]
8260: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
8270: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
8280: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
8290: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
82a0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
82b0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
82c0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
82d0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
82e0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
82f0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
8300: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
8310: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
8320: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
8330: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
8340: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
8350: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
8360: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
8370: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
8380: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
8390: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
83a0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
83b0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
83c0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
83d0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
83e0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
83f0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
8400: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
8410: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
8420: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
8430: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
8440: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
8450: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
8460: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
8470: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
8480: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
8490: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
84a0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ite()..**.** If
84b0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 xRead() returns
84c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
84d0: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 RT_READ it must
84e0: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 also fill.** in
84f0: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 the unread porti
8500: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 ons of the buffe
8510: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 r with zeros. A
8520: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 VFS that.** fai
8530: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 ls to zero-fill
8540: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 short reads migh
8550: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 t seem to work.
8560: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 However,.** fai
8570: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c lure to zero-fil
8580: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 l short reads wi
8590: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 ll eventually le
85a0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 ad to.** databas
85b0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f e corruption..*/
85c0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
85d0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
85e0: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ds sqlite3_io_me
85f0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
8600: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
8610: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f {. int iVersio
8620: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 n;. int (*xClos
8630: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
8640: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 );. int (*xRead
8650: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8660: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 void*, int iAmt
8670: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
8680: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a iOfst);. int (*
8690: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f xWrite)(sqlite3_
86a0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 file*, const voi
86b0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 d*, int iAmt, sq
86c0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 lite3_int64 iOfs
86d0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 t);. int (*xTru
86e0: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 ncate)(sqlite3_f
86f0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
8700: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 t64 size);. int
8710: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 (*xSync)(sqlite
8720: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 3_file*, int fla
8730: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 gs);. int (*xFi
8740: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f leSize)(sqlite3_
8750: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
8760: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 nt64 *pSize);.
8770: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c int (*xLock)(sql
8780: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 ite3_file*, int)
8790: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 ;. int (*xUnloc
87a0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
87b0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a , int);. int (*
87c0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f xCheckReservedLo
87d0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
87e0: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 *, int *pResOut)
87f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 ;. int (*xFileC
8800: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f ontrol)(sqlite3_
8810: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 file*, int op, v
8820: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e oid *pArg);. in
8830: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 t (*xSectorSize)
8840: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
8850: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 . int (*xDevice
8860: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 Characteristics)
8870: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
8880: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 . /* Methods ab
8890: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f ove are valid fo
88a0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 r version 1 */.
88b0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 int (*xShmMap)(
88c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
88d0: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a nt iPg, int pgsz
88e0: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 , int, void vola
88f0: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 tile**);. int (
8900: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 *xShmLock)(sqlit
8910: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 e3_file*, int of
8920: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 fset, int n, int
8930: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 flags);. void
8940: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 (*xShmBarrier)(s
8950: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
8960: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 int (*xShmUnmap
8970: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8980: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 int deleteFlag)
8990: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 ;. /* Methods a
89a0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 bove are valid f
89b0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a or version 2 */.
89c0: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 int (*xFetch)(
89d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
89e0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
89f0: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f st, int iAmt, vo
8a00: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 id **pp);. int
8a10: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 (*xUnfetch)(sqli
8a20: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
8a30: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 e3_int64 iOfst,
8a40: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d void *p);. /* M
8a50: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
8a60: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 valid for versi
8a70: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 on 3 */. /* Add
8a80: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 itional methods
8a90: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
8aa0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
8ab0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
8ac0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 I3REF: Standard
8ad0: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 File Control Opc
8ae0: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 odes.** KEYWORDS
8af0: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 : {file control
8b00: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 opcodes} {file c
8b10: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a ontrol opcode}.*
8b20: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 *.** These integ
8b30: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 er constants are
8b40: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 opcodes for the
8b50: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
8b60: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b thod.** of the [
8b70: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
8b80: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 ds] object and f
8b90: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f or the [sqlite3_
8ba0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a file_control()].
8bb0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a ** interface..**
8bc0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
8bd0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c [[SQLITE_FCNTL_L
8be0: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 OCKSTATE]].** Th
8bf0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
8c00: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 LOCKSTATE] opcod
8c10: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 e is used for de
8c20: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a bugging. This.*
8c30: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 * opcode causes
8c40: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
8c50: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 method to write
8c60: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 the current sta
8c70: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 te of.** the loc
8c80: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 k (one of [SQLIT
8c90: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 E_LOCK_NONE], [S
8ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
8cb0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c D],.** [SQLITE_L
8cc0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b OCK_RESERVED], [
8cd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
8ce0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 ING], or [SQLITE
8cf0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d _LOCK_EXCLUSIVE]
8d00: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 ).** into an int
8d10: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 eger that the pA
8d20: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e rg argument poin
8d30: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 ts to. This capa
8d40: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 bility.** is use
8d50: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 d during testing
8d60: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 and is only ava
8d70: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 ilable when the
8d80: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 SQLITE_TEST.** c
8d90: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
8da0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a on is used..**.*
8db0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
8dc0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d CNTL_SIZE_HINT]]
8dd0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
8de0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d FCNTL_SIZE_HINT]
8df0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
8e00: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 by SQLite to giv
8e10: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 e the VFS.** lay
8e20: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 er a hint of how
8e30: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 large the datab
8e40: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 ase file will gr
8e50: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 ow to be during
8e60: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 the.** current t
8e70: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 ransaction. Thi
8e80: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 s hint is not gu
8e90: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 aranteed to be a
8ea0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a ccurate but it.*
8eb0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 * is often close
8ec0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e . The underlyin
8ed0: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f g VFS might choo
8ee0: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 se to preallocat
8ef0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 e database.** fi
8f00: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f le space based o
8f10: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f n this hint in o
8f20: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 rder to help wri
8f30: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 tes to the datab
8f40: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 ase.** file run
8f50: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c faster..**.** <l
8f60: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
8f70: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a _CHUNK_SIZE]].**
8f80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
8f90: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f TL_CHUNK_SIZE] o
8fa0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
8fb0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 request that th
8fc0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 e VFS.** extends
8fd0: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 and truncates t
8fe0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
8ff0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 in chunks of a
9000: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a size specified.*
9010: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 * by the user. T
9020: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
9030: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 nt to [sqlite3_f
9040: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 ile_control()] s
9050: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 hould .** point
9060: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 to an integer (t
9070: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e ype int) contain
9080: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e ing the new chun
9090: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a k-size to use.**
90a0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 for the nominat
90b0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c ed database. All
90c0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 ocating database
90d0: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c file space in l
90e0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 arge.** chunks (
90f0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d say 1MB at a tim
9100: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 e), may reduce f
9110: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d ile-system fragm
9120: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 entation and.**
9130: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 improve performa
9140: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 nce on some syst
9150: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ems..**.** <li>[
9160: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 [SQLITE_FCNTL_FI
9170: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 LE_POINTER]].**
9180: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
9190: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 L_FILE_POINTER]
91a0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
91b0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 o obtain a point
91c0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 er.** to the [sq
91d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
91e0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ct associated wi
91f0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 th a particular
9200: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
9210: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 ection. See the
9220: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
9230: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 ontrol()] docume
9240: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 ntation for.** a
9250: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
9260: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ation..**.** <li
9270: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
9280: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a SYNC_OMITTED]].*
9290: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 * No longer in u
92a0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b se..**.** <li>[[
92b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e SQLITE_FCNTL_SYN
92c0: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 C]].** The [SQLI
92d0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f TE_FCNTL_SYNC] o
92e0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 pcode is generat
92f0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 ed internally by
9300: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 SQLite and.** s
9310: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 ent to the VFS i
9320: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 mmediately befor
9330: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 e the xSync meth
9340: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e od is invoked on
9350: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 a.** database f
9360: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 ile descriptor.
9370: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 Or, if the xSync
9380: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 method is not i
9390: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 nvoked .** becau
93a0: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 se the user has
93b0: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 configured SQLit
93c0: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 e with .** [PRAG
93d0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c MA synchronous |
93e0: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e PRAGMA synchron
93f0: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 ous=OFF] it is i
9400: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 nvoked in place
9410: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 .** of the xSync
9420: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 method. In most
9430: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e cases, the poin
9440: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 ter argument pas
9450: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 sed with.** this
9460: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 file-control is
9470: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 NULL. However,
9480: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 if the database
9490: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 file is being sy
94a0: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 nced.** as part
94b0: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 of a multi-datab
94c0: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 ase commit, the
94d0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 argument points
94e0: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 to a nul-termina
94f0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f ted.** string co
9500: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 ntaining the tra
9510: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 nsactions master
9520: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 -journal file na
9530: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a me. VFSes that .
9540: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 ** do not need t
9550: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c his signal shoul
9560: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 d silently ignor
9570: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 e this opcode. A
9580: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 pplications .**
9590: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 should not call
95a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
95b0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 ntrol()] with th
95c0: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 is opcode as doi
95d0: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 ng so may .** di
95e0: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 srupt the operat
95f0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 ion of the speci
9600: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 alized VFSes tha
9610: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e t do require it.
9620: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 .**.** <li>[[S
9630: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d QLITE_FCNTL_COMM
9640: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a IT_PHASETWO]].**
9650: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
9660: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 TL_COMMIT_PHASET
9670: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 WO] opcode is ge
9680: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c nerated internal
9690: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ly by SQLite.**
96a0: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 and sent to the
96b0: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e VFS after a tran
96c0: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e saction has been
96d0: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 committed immed
96e0: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 iately.** but be
96f0: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 fore the databas
9700: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 e is unlocked. V
9710: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 FSes that do not
9720: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 need this signa
9730: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 l.** should sile
9740: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 ntly ignore this
9750: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 opcode. Applica
9760: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 tions should not
9770: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 call.** [sqlite
9780: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
9790: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f ] with this opco
97a0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d de as doing so m
97b0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a ay disrupt the .
97c0: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 ** operation of
97d0: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 the specialized
97e0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 VFSes that do re
97f0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a quire it. .**.*
9800: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
9810: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 CNTL_WIN32_AV_RE
9820: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 TRY]].** ^The [S
9830: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
9840: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 2_AV_RETRY] opco
9850: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f de is used to co
9860: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 nfigure automati
9870: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 c.** retry count
9880: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 s and intervals
9890: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b for certain disk
98a0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 I/O operations
98b0: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f for the.** windo
98c0: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 ws [VFS] in orde
98d0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 r to provide rob
98e0: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 ustness in the p
98f0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e resence of.** an
9900: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d ti-virus program
9910: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 s. By default,
9920: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 the windows VFS
9930: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 will retry file
9940: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 read,.** file wr
9950: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 ite, and file de
9960: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 lete operations
9970: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 up to 10 times,
9980: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 with a delay.**
9990: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e of 25 millisecon
99a0: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 ds before the fi
99b0: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 rst retry and wi
99c0: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 th the delay inc
99d0: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e reasing.** by an
99e0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d additional 25 m
99f0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 illiseconds with
9a00: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 each subsequent
9a10: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a retry. This.**
9a20: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 opcode allows t
9a30: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 hese two values
9a40: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 (10 retries and
9a50: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 25 milliseconds
9a60: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 of delay).** to
9a70: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 be adjusted. Th
9a80: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 e values are cha
9a90: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 nged for all dat
9aa0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
9ab0: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 s.** within the
9ac0: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 same process. T
9ad0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 he argument is a
9ae0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 pointer to an a
9af0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 rray of two.** i
9b00: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 ntegers where th
9b10: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 e first integer
9b20: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 i the new retry
9b30: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 count and the se
9b40: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 cond.** integer
9b50: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 is the delay. I
9b60: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 f either integer
9b70: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
9b80: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a en the setting.*
9b90: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 * is not changed
9ba0: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 but instead the
9bb0: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 prior value of
9bc0: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 that setting is
9bd0: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 written.** into
9be0: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c the array entry,
9bf0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 allowing the cu
9c00: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 rrent retry sett
9c10: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e ings to be.** in
9c20: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 terrogated. The
9c30: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 zDbName paramet
9c40: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a er is ignored..*
9c50: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9c60: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f E_FCNTL_PERSIST_
9c70: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 WAL]].** ^The [S
9c80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 QLITE_FCNTL_PERS
9c90: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 IST_WAL] opcode
9ca0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f is used to set o
9cb0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 r query the.** p
9cc0: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c ersistent [WAL |
9cd0: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 Write Ahead Log
9ce0: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 ] setting. By d
9cf0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 efault, the auxi
9d00: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 liary.** write a
9d10: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 head log and sha
9d20: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 red memory files
9d30: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 used for transa
9d40: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a ction control.**
9d50: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c are automatical
9d60: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 ly deleted when
9d70: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 the latest conne
9d80: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 ction to the dat
9d90: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e abase.** closes.
9da0: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 Setting persis
9db0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 tent WAL mode ca
9dc0: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 uses those files
9dd0: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 to persist afte
9de0: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 r.** close. Per
9df0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 sisting the file
9e00: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e s is useful when
9e10: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 other processes
9e20: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 that do not.**
9e30: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 have write permi
9e40: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 ssion on the dir
9e50: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e ectory containin
9e60: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 g the database f
9e70: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 ile want.** to r
9e80: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 ead the database
9e90: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 file, as the WA
9ea0: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d L and shared mem
9eb0: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 ory files must e
9ec0: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 xist.** in order
9ed0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 for the databas
9ee0: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 e to be readable
9ef0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 . The fourth pa
9f00: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 rameter to.** [s
9f10: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
9f20: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 rol()] for this
9f30: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 opcode should be
9f40: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
9f50: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 integer..** Tha
9f60: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 t integer is 0 t
9f70: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 o disable persis
9f80: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 tent WAL mode or
9f90: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 1 to enable per
9fa0: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d sistent.** WAL m
9fb0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 ode. If the int
9fc0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e eger is -1, then
9fd0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 it is overwritt
9fe0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 en with the curr
9ff0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 ent.** WAL persi
a000: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a stence setting..
a010: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
a020: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 TE_FCNTL_POWERSA
a030: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a FE_OVERWRITE]].*
a040: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
a050: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f CNTL_POWERSAFE_O
a060: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 VERWRITE] opcode
a070: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 is used to set
a080: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 or query the.**
a090: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 persistent "powe
a0a0: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 rsafe-overwrite"
a0b0: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 or "PSOW" setti
a0c0: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 ng. The PSOW se
a0d0: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 tting.** determi
a0e0: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f nes the [SQLITE_
a0f0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f IOCAP_POWERSAFE_
a100: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f OVERWRITE] bit o
a110: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 f the.** xDevice
a120: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 Characteristics
a130: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 methods. The fou
a140: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
a150: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
a160: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 e_control()] for
a170: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f this opcode sho
a180: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 uld be a pointer
a190: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a to an integer..
a1a0: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 ** That integer
a1b0: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
a1c0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 zero-damage mode
a1d0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 or 1 to enable
a1e0: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d zero-damage.** m
a1f0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 ode. If the int
a200: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e eger is -1, then
a210: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 it is overwritt
a220: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 en with the curr
a230: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 ent.** zero-dama
a240: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e ge mode setting.
a250: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
a260: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 ITE_FCNTL_OVERWR
a270: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 ITE]].** ^The [S
a280: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
a290: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 WRITE] opcode is
a2a0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 invoked by SQLi
a2b0: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 te after opening
a2c0: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e .** a write tran
a2d0: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 saction to indic
a2e0: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 ate that, unless
a2f0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 it is rolled ba
a300: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 ck for some.** r
a310: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 eason, the entir
a320: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
a330: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 will be overwrit
a340: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 ten by the curre
a350: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 nt .** transacti
a360: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 on. This is used
a370: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 by VACUUM opera
a380: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 tions..**.** <li
a390: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
a3a0: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 VFSNAME]].** ^Th
a3b0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
a3c0: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 VFSNAME] opcode
a3d0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
a3e0: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 btain the names
a3f0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 of.** all [VFSes
a400: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 ] in the VFS sta
a410: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 ck. The names a
a420: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 re of all VFS sh
a430: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 ims and the.** f
a440: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 inal bottom-leve
a450: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 l VFS are writte
a460: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 n into memory ob
a470: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 tained from .**
a480: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
a490: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c )] and the resul
a4a0: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 t is stored in t
a4b0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c he char* variabl
a4c0: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f e.** that the fo
a4d0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f urth parameter o
a4e0: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f f [sqlite3_file_
a4f0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 control()] point
a500: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c s to..** The cal
a510: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ler is responsib
a520: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 le for freeing t
a530: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 he memory when d
a540: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a one. As with.**
a550: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f all file-contro
a560: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 l actions, there
a570: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 is no guarantee
a580: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 that this will
a590: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 actually.** do a
a5a0: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 nything. Caller
a5b0: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c s should initial
a5c0: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 ize the char* va
a5d0: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c riable to a NULL
a5e0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 .** pointer in c
a5f0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f ase this file-co
a600: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 ntrol is not imp
a610: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 lemented. This
a620: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 file-control.**
a630: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 is intended for
a640: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f diagnostic use o
a650: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b nly..**.** <li>[
a660: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
a670: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 AGMA]].** ^Whene
a680: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 ver a [PRAGMA] s
a690: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 tatement is pars
a6a0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 ed, an [SQLITE_F
a6b0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a CNTL_PRAGMA] .**
a6c0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 file control is
a6d0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 sent to the ope
a6e0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d n [sqlite3_file]
a6f0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f object correspo
a700: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 nding.** to the
a710: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f database file to
a720: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d which the pragm
a730: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 a statement refe
a740: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e rs. ^The argumen
a750: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c t.** to the [SQL
a760: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
a770: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 ] file control i
a780: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a s an array of.**
a790: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
a7a0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e ings (char**) in
a7b0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e which the secon
a7c0: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 d element of the
a7d0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 array.** is the
a7e0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 name of the pra
a7f0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 gma and the thir
a800: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 d element is the
a810: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
a820: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 .** pragma or NU
a830: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 LL if the pragma
a840: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 has no argument
a850: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 . ^The handler
a860: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 for an.** [SQLIT
a870: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
a880: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e file control can
a890: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 optionally make
a8a0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 the first eleme
a8b0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 nt.** of the cha
a8c0: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 r** argument poi
a8d0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f nt to a string o
a8e0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
a8f0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d lite3_mprintf()]
a900: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 .** or the equiv
a910: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 alent and that s
a920: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d tring will becom
a930: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 e the result of
a940: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a the pragma or.**
a950: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
a960: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 ge if the pragma
a970: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a fails. ^If the.
a980: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [SQLITE_FCNTL
a990: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
a9a0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 ntrol returns [S
a9b0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c QLITE_NOTFOUND],
a9c0: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a then normal .**
a9d0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 [PRAGMA] proces
a9e0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 sing continues.
a9f0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 ^If the [SQLITE
aa00: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a _FCNTL_PRAGMA].*
aa10: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 * file control r
aa20: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
aa30: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 K], then the par
aa40: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 ser assumes that
aa50: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 the.** VFS has
aa60: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 handled the PRAG
aa70: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 MA itself and th
aa80: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 e parser generat
aa90: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 es a no-op.** pr
aaa0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
aab0: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e if result strin
aac0: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 g is NULL, or th
aad0: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 at returns a cop
aae0: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 y.** of the resu
aaf0: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 lt string if the
ab00: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e string is non-N
ab10: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ULL..** ^If the
ab20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
ab30: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 AGMA] file contr
ab40: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e ol returns.** an
ab50: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 y result code ot
ab60: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
ab70: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f _OK] or [SQLITE_
ab80: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 NOTFOUND], that
ab90: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 means.** that th
aba0: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 e VFS encountere
abb0: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 d an error while
abc0: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 handling the [P
abd0: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a RAGMA] and the.*
abe0: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 * compilation of
abf0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c the PRAGMA fail
ac00: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e s with an error.
ac10: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ^The [SQLITE_F
ac20: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 CNTL_PRAGMA].**
ac30: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 file control occ
ac40: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e urs at the begin
ac50: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 ning of pragma s
ac60: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 tatement analysi
ac70: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 s and so.** it i
ac80: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 s able to overri
ac90: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 de built-in [PRA
aca0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e GMA] statements.
acb0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
acc0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 ITE_FCNTL_BUSYHA
acd0: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 NDLER]].** ^The
ace0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 [SQLITE_FCNTL_BU
acf0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 SYHANDLER].** fi
ad00: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 le-control may b
ad10: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c e invoked by SQL
ad20: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ite on the datab
ad30: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a ase file handle.
ad40: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 ** shortly after
ad50: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e it is opened in
ad60: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 order to provid
ad70: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 e a custom VFS w
ad80: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f ith access.** to
ad90: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 the connections
ada0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 busy-handler ca
adb0: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 llback. The argu
adc0: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 ment is of type
add0: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 (void **).** - a
ade0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 n array of two (
adf0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 void *) values.
ae00: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 The first (void
ae10: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e *) actually poin
ae20: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 ts.** to a funct
ae30: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 ion of type (int
ae40: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 (*)(void *)). I
ae50: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b n order to invok
ae60: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e e the connection
ae70: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 s.** busy-handle
ae80: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e r, this function
ae90: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b should be invok
aea0: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f ed with the seco
aeb0: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a nd (void *) in.*
aec0: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 * the array as t
aed0: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 he only argument
aee0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 . If it returns
aef0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 non-zero, then t
af00: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 he operation.**
af10: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 should be retrie
af20: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 d. If it returns
af30: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f zero, the custo
af40: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 m VFS should aba
af50: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 ndon the.** curr
af60: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a ent operation..*
af70: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
af80: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 E_FCNTL_TEMPFILE
af90: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 NAME]].** ^Appli
afa0: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b cation can invok
afb0: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 e the [SQLITE_FC
afc0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 NTL_TEMPFILENAME
afd0: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a ] file-control.*
afe0: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 * to have SQLite
aff0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 generate a.** t
b000: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d emporary filenam
b010: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 e using the same
b020: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 algorithm that
b030: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 is followed to g
b040: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f enerate.** tempo
b050: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 rary filenames f
b060: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 or TEMP tables a
b070: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 nd other interna
b080: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 l uses. The.**
b090: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
b0a0: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 be a char** whic
b0b0: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 h will be filled
b0c0: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 with the filena
b0d0: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e me.** written in
b0e0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
b0f0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
b100: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 _malloc()]. The
b110: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a caller should.*
b120: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 * invoke [sqlite
b130: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 3_free()] on the
b140: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 result to avoid
b150: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a a memory leak..
b160: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
b170: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 TE_FCNTL_MMAP_SI
b180: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ZE]].** The [SQL
b190: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 ITE_FCNTL_MMAP_S
b1a0: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f IZE] file contro
b1b0: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 l is used to que
b1c0: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a ry or set the.**
b1d0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
b1e0: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69 of bytes that wi
b1f0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d ll be used for m
b200: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f emory-mapped I/O
b210: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e ..** The argumen
b220: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
b230: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 o a value of typ
b240: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 e sqlite3_int64
b250: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 that.** is an ad
b260: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e visory maximum n
b270: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
b280: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 n the file to me
b290: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a mory map. The.*
b2a0: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 * pointer is ove
b2b0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 rwritten with th
b2c0: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 e old value. Th
b2d0: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 e limit is not c
b2e0: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 hanged if.** the
b2f0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c value originall
b300: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 y pointed to is
b310: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f negative, and so
b320: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d the current lim
b330: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 it .** can be qu
b340: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 eried by passing
b350: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f in a pointer to
b360: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 a negative numb
b370: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c er. This.** fil
b380: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 e-control is use
b390: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 d internally to
b3a0: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d implement [PRAGM
b3b0: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a A mmap_size]..**
b3c0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
b3d0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a _FCNTL_TRACE]].*
b3e0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
b3f0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 NTL_TRACE] file
b400: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 control provides
b410: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d advisory inform
b420: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 ation.** to the
b430: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 VFS about what t
b440: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 he higher layers
b450: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 of the SQLite s
b460: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a tack are doing..
b470: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e ** This file con
b480: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 trol is used by
b490: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 some VFS activit
b4a0: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 y tracing [shims
b4b0: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 ]..** The argume
b4c0: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 nt is a zero-ter
b4d0: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 minated string.
b4e0: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 Higher layers i
b4f0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 n the.** SQLite
b500: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 stack may genera
b510: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 te instances of
b520: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f this file contro
b530: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c l if.** the [SQL
b540: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 ITE_USE_FCNTL_TR
b550: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ACE] compile-tim
b560: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 e option is enab
b570: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b led..**.** <li>[
b580: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 [SQLITE_FCNTL_HA
b590: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 S_MOVED]].** The
b5a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 [SQLITE_FCNTL_H
b5b0: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 AS_MOVED] file c
b5c0: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 ontrol interpret
b5d0: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 s its argument a
b5e0: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 s a.** pointer t
b5f0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 o an integer and
b600: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f it writes a boo
b610: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 lean into that i
b620: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 nteger depending
b630: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f .** on whether o
b640: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 r not the file h
b650: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c as been renamed,
b660: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 moved, or delet
b670: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 ed since it.** w
b680: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e as first opened.
b690: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
b6a0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
b6b0: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 SET_HANDLE]].**
b6c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
b6d0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 L_WIN32_SET_HAND
b6e0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 LE] opcode is us
b6f0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 ed for debugging
b700: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
b710: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 e causes the xFi
b720: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
b730: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c to swap the fil
b740: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 e handle with th
b750: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 e one.** pointed
b760: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 to by the pArg
b770: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 argument. This
b780: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 capability is us
b790: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
b7a0: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 g.** and only ne
b7b0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 eds to be suppor
b7c0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f ted when SQLITE_
b7d0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e TEST is defined.
b7e0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
b7f0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c ITE_FCNTL_WAL_BL
b800: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 OCK]].** The [SQ
b810: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 LITE_FCNTL_WAL_B
b820: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 LOCK] is a signa
b830: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 l to the VFS lay
b840: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 er that it might
b850: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 .** be advantage
b860: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 ous to block on
b870: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 the next WAL loc
b880: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 k if the lock is
b890: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 not immediately
b8a0: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 .** available.
b8b0: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 The WAL subsyste
b8c0: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69 m issues this si
b8d0: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 gnal during rare
b8e0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 .** circumstance
b8f0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 s in order to fi
b900: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 x a problem with
b910: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 priority invers
b920: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ion..** Applicat
b930: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e ions should <em>
b940: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 not</em> use thi
b950: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a s file-control..
b960: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
b970: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d TE_FCNTL_ZIPVFS]
b980: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
b990: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f _FCNTL_ZIPVFS] o
b9a0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 pcode is impleme
b9b0: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f nted by zipvfs o
b9c0: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a nly. All other.*
b9d0: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 * VFS should ret
b9e0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f urn SQLITE_NOTFO
b9f0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 UND for this opc
ba00: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ode..**.** <li>[
ba10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 [SQLITE_FCNTL_RB
ba20: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 U]].** The [SQLI
ba30: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 TE_FCNTL_RBU] op
ba40: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e code is implemen
ba50: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69 ted by the speci
ba60: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a al VFS used by.*
ba70: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73 * the RBU extens
ba80: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f ion only. All o
ba90: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 ther VFS should
baa0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f return SQLITE_NO
bab0: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 TFOUND for.** th
bac0: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 is opcode. .**
bad0: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </ul>.*/.#define
bae0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f SQLITE_FCNTL_LO
baf0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 CKSTATE
bb00: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
bb10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 SQLITE_FCNTL_GET
bb20: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
bb30: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
bb40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f QLITE_FCNTL_SET_
bb50: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 LOCKPROXYFILE
bb60: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
bb70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f LITE_FCNTL_LAST_
bb80: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 ERRNO
bb90: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
bba0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 ITE_FCNTL_SIZE_H
bbb0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 INT
bbc0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 5.#define SQLI
bbd0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 TE_FCNTL_CHUNK_S
bbe0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 IZE
bbf0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
bc00: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 E_FCNTL_FILE_POI
bc10: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 NTER
bc20: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 7.#define SQLITE
bc30: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 _FCNTL_SYNC_OMIT
bc40: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 TED 8
bc50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
bc60: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 FCNTL_WIN32_AV_R
bc70: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a ETRY 9.
bc80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
bc90: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c CNTL_PERSIST_WAL
bca0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 10.#
bcb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
bcc0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 NTL_OVERWRITE
bcd0: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 11.#d
bce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
bcf0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 TL_VFSNAME
bd00: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 12.#de
bd10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
bd20: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 L_POWERSAFE_OVER
bd30: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 WRITE 13.#def
bd40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
bd50: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 _PRAGMA
bd60: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 14.#defi
bd70: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
bd80: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 BUSYHANDLER
bd90: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 15.#defin
bda0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 e SQLITE_FCNTL_T
bdb0: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 EMPFILENAME
bdc0: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 16.#define
bdd0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d SQLITE_FCNTL_MM
bde0: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 AP_SIZE
bdf0: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 18.#define
be00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 SQLITE_FCNTL_TRA
be10: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CE
be20: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 19.#define S
be30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f QLITE_FCNTL_HAS_
be40: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20 MOVED
be50: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 20.#define SQ
be60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 LITE_FCNTL_SYNC
be70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
be80: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 21.#define SQL
be90: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 ITE_FCNTL_COMMIT
bea0: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 _PHASETWO
beb0: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 22.#define SQLI
bec0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 TE_FCNTL_WIN32_S
bed0: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 ET_HANDLE
bee0: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 23.#define SQLIT
bef0: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 E_FCNTL_WAL_BLOC
bf00: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 K 2
bf10: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
bf20: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 _FCNTL_ZIPVFS
bf30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 25
bf40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
bf50: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20 FCNTL_RBU
bf60: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 26.
bf70: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e ./* deprecated n
bf80: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ames */.#define
bf90: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 SQLITE_GET_LOCKP
bfa0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 ROXYFILE SQ
bfb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c LITE_FCNTL_GET_L
bfc0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 OCKPROXYFILE.#de
bfd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f fine SQLITE_SET_
bfe0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 LOCKPROXYFILE
bff0: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f SQLITE_FCNTL_
c000: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c SET_LOCKPROXYFIL
c010: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 E.#define SQLITE
c020: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 _LAST_ERRNO
c030: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 SQLITE_F
c040: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a CNTL_LAST_ERRNO.
c050: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
c060: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a : Mutex Handle.*
c070: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d *.** The mutex m
c080: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c odule within SQL
c090: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c ite defines [sql
c0a0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 ite3_mutex] to b
c0b0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 e an.** abstract
c0c0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 type for a mute
c0d0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 x object. The S
c0e0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 QLite core never
c0f0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 looks.** at the
c100: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 internal repres
c110: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b entation of an [
c120: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 sqlite3_mutex].
c130: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c It only.** deal
c140: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 s with pointers
c150: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
c160: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a mutex] object..*
c170: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 *.** Mutexes are
c180: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b created using [
c190: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
c1a0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 loc()]..*/.typed
c1b0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
c1c0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 3_mutex sqlite3_
c1d0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 mutex;../*.** CA
c1e0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
c1f0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a face Object.**.*
c200: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
c210: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
c220: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
c230: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
c240: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c tween.** the SQL
c250: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 ite core and the
c260: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 underlying oper
c270: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 ating system. T
c280: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 he "vfs".** in t
c290: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f he name of the o
c2a0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 bject stands for
c2b0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 "virtual file s
c2c0: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 ystem". See.**
c2d0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 the [VFS | VFS d
c2e0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
c2f0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d r further inform
c300: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
c310: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 value of the iV
c320: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 ersion field is
c330: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 initially 1 but
c340: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e may be larger in
c350: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 .** future versi
c360: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 ons of SQLite.
c370: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 Additional field
c380: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 s may be appende
c390: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a d to this.** obj
c3a0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 ect when the iVe
c3b0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 rsion value is i
c3c0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 ncreased. Note
c3d0: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 that the structu
c3e0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c re.** of the sql
c3f0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 ite3_vfs object
c400: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 changes in the t
c410: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 ransaction betwe
c420: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 en.** SQLite ver
c430: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 sion 3.5.9 and 3
c440: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 .6.0 and yet the
c450: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 iVersion field
c460: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 was not.** modif
c470: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ied..**.** The s
c480: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 zOsFile field is
c490: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
c4a0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c subclassed [sql
c4b0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 ite3_file].** st
c4c0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 ructure used by
c4d0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 this VFS. mxPat
c4e0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 hname is the max
c4f0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a imum length of.*
c500: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 * a pathname in
c510: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 this VFS..**.**
c520: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 Registered sqlit
c530: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 e3_vfs objects a
c540: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e re kept on a lin
c550: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 ked list formed
c560: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 by.** the pNext
c570: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 pointer. The [s
c580: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 qlite3_vfs_regis
c590: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ter()].** and [s
c5a0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 qlite3_vfs_unreg
c5b0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 ister()] interfa
c5c0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 ces manage this
c5d0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 list.** in a thr
c5e0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 ead-safe way. T
c5f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f he [sqlite3_vfs_
c600: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 find()] interfac
c610: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 e.** searches th
c620: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 e list. Neither
c630: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
c640: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 code nor the VF
c650: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 S.** implementat
c660: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 ion should use t
c670: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 he pNext pointer
c680: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 ..**.** The pNex
c690: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f t field is the o
c6a0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 nly field in the
c6b0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 sqlite3_vfs.**
c6c0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 structure that S
c6d0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 QLite will ever
c6e0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 modify. SQLite
c6f0: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 will only access
c700: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 .** or modify th
c710: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 is field while h
c720: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 olding a particu
c730: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 lar static mutex
c740: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
c750: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 tion should neve
c760: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e r modify anythin
c770: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c g within the sql
c780: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 ite3_vfs.** obje
c790: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 ct once the obje
c7a0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 ct has been regi
c7b0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 stered..**.** Th
c7c0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f e zName field ho
c7d0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 lds the name of
c7e0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 the VFS module.
c7f0: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a The name must.*
c800: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f * be unique acro
c810: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c ss all VFS modul
c820: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 es..**.** [[sqli
c830: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a te3_vfs.xOpen]].
c840: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 ** ^SQLite guara
c850: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a ntees that the z
c860: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
c870: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 er to xOpen.** i
c880: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 s either a NULL
c890: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e pointer or strin
c8a0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 g obtained.** fr
c8b0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 om xFullPathname
c8c0: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f () with an optio
c8d0: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 nal suffix added
c8e0: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 ..** ^If a suffi
c8f0: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 x is added to th
c900: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 e zFilename para
c910: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a meter, it will.*
c920: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 * consist of a s
c930: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 ingle "-" charac
c940: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 ter followed by
c950: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 no more than.**
c960: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 11 alphanumeric
c970: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 and/or "-" chara
c980: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 cters..** ^SQLit
c990: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e e further guaran
c9a0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 tees that.** the
c9b0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 string will be
c9c0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e valid and unchan
c9d0: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 ged until xClose
c9e0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e () is.** called.
c9f0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
ca00: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 previous sentenc
ca10: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 e,.** the [sqlit
ca20: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 e3_file] can saf
ca30: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e ely store a poin
ca40: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 ter to the.** fi
ca50: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 lename if it nee
ca60: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 ds to remember t
ca70: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 he filename for
ca80: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 some reason..**
ca90: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 If the zFilename
caa0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
cab0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f pen is a NULL po
cac0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e inter then xOpen
cad0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 .** must invent
cae0: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 its own temporar
caf0: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 y name for the f
cb00: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 ile. ^Whenever
cb10: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d the .** xFilenam
cb20: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e e parameter is N
cb30: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f ULL it will also
cb40: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 be the case tha
cb50: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 t the.** flags p
cb60: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e arameter will in
cb70: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 clude [SQLITE_OP
cb80: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
cb90: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 ]..**.** The fla
cba0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
cbb0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 Open() includes
cbc0: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a all bits set in.
cbd0: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 ** the flags arg
cbe0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 ument to [sqlite
cbf0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 3_open_v2()]. O
cc00: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r if [sqlite3_op
cc10: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c en()].** or [sql
cc20: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 ite3_open16()] i
cc30: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 s used, then fla
cc40: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c gs includes at l
cc50: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f east.** [SQLITE_
cc60: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 OPEN_READWRITE]
cc70: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 | [SQLITE_OPEN_C
cc80: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 REATE]. .** If x
cc90: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 Open() opens a f
cca0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 ile read-only th
ccb0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 en it sets *pOut
ccc0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c Flags to.** incl
ccd0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ude [SQLITE_OPEN
cce0: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 _READONLY]. Oth
ccf0: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 er bits in *pOut
cd00: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 Flags may be set
cd10: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 ..**.** ^(SQLite
cd20: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f will also add o
cd30: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
cd40: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 ing flags to the
cd50: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c xOpen().** call
cd60: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 , depending on t
cd70: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 he object being
cd80: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 opened:.**.** <u
cd90: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c l>.** <li> [SQL
cda0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
cdb0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
cdc0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 TE_OPEN_MAIN_JOU
cdd0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
cde0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
cdf0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
ce00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
ce10: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
ce20: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
ce30: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 RANSIENT_DB].**
ce40: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
ce50: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a EN_SUBJOURNAL].*
ce60: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
ce70: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
ce80: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
ce90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a QLITE_OPEN_WAL].
cea0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a ** </ul>)^.**.**
ceb0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d The file I/O im
cec0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e plementation can
ced0: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 use the object
cee0: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a type flags to.**
cef0: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 change the way
cf00: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 it deals with fi
cf10: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c les. For exampl
cf20: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f e, an applicatio
cf30: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e n.** that does n
cf40: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 ot care about cr
cf50: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 ash recovery or
cf60: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d rollback might m
cf70: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 ake.** the open
cf80: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c of a journal fil
cf90: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 e a no-op. Writ
cfa0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e es to this journ
cfb0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f al would.** also
cfc0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 be no-ops, and
cfd0: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 any attempt to r
cfe0: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 ead the journal
cff0: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 would return.**
d000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f SQLITE_IOERR. O
d010: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 r the implementa
d020: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 tion might recog
d030: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 nize that a data
d040: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c base.** file wil
d050: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d l be doing page-
d060: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 aligned sector r
d070: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 eads and writes
d080: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f in a random.** o
d090: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 rder and set up
d0a0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 its I/O subsyste
d0b0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a m accordingly..*
d0c0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 *.** SQLite migh
d0d0: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f t also add one o
d0e0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
d0f0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 flags to the xOp
d100: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a en method:.**.**
d110: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
d120: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
d130: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 EONCLOSE].** <li
d140: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 > [SQLITE_OPEN_E
d150: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 XCLUSIVE].** </u
d160: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 l>.**.** The [SQ
d170: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
d180: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 ONCLOSE] flag me
d190: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f ans the file sho
d1a0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 uld be.** delete
d1b0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f d when it is clo
d1c0: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 sed. ^The [SQLI
d1d0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
d1e0: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 CLOSE].** will b
d1f0: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 e set for TEMP d
d200: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 atabases and the
d210: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 ir journals, tra
d220: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 nsient.** databa
d230: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 ses, and subjour
d240: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nals..**.** ^The
d250: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
d260: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 CLUSIVE] flag is
d270: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 always used in
d280: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 conjunction.** w
d290: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
d2a0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 OPEN_CREATE] fla
d2b0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 g, which are bot
d2c0: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e h directly.** an
d2d0: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f alogous to the O
d2e0: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 _EXCL and O_CREA
d2f0: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 T flags of the P
d300: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 OSIX open().** A
d310: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f PI. The SQLITE_
d320: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 OPEN_EXCLUSIVE f
d330: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 lag, when paired
d340: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 with the .** SQ
d350: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
d360: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 , is used to ind
d370: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 icate that file
d380: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a should always.**
d390: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 be created, and
d3a0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 that it is an e
d3b0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 rror if it alrea
d3c0: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 dy exists..** It
d3d0: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 is <i>not</i> u
d3e0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 sed to indicate
d3f0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 the file should
d400: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f be opened .** fo
d410: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 r exclusive acce
d420: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 ss..**.** ^At le
d430: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 ast szOsFile byt
d440: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 es of memory are
d450: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 allocated by SQ
d460: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 Lite.** to hold
d470: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
d480: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 le] structure pa
d490: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 ssed as the thir
d4a0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f d.** argument to
d4b0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 xOpen. The xOp
d4c0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e en method does n
d4d0: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c ot have to.** al
d4e0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 locate the struc
d4f0: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 ture; it should
d500: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e just fill it in.
d510: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 Note that.** t
d520: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 he xOpen method
d530: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c must set the sql
d540: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
d550: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 ds to either.**
d560: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 a valid [sqlite3
d570: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
d580: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 ect or to NULL.
d590: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a xOpen must do.*
d5a0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 * this even if t
d5b0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 he open fails.
d5c0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 SQLite expects t
d5d0: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f hat the sqlite3_
d5e0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a file.pMethods.**
d5f0: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 element will be
d600: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 valid after xOp
d610: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 en returns regar
d620: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 dless of the suc
d630: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 cess.** or failu
d640: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 re of the xOpen
d650: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 call..**.** [[sq
d660: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 lite3_vfs.xAcces
d670: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 s]].** ^The flag
d680: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 s argument to xA
d690: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b ccess() may be [
d6a0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
d6b0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 ISTS].** to test
d6c0: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e for the existen
d6d0: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 ce of a file, or
d6e0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
d6f0: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a READWRITE] to.**
d700: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 test whether a
d710: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 file is readable
d720: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f and writable, o
d730: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 r [SQLITE_ACCESS
d740: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 _READ].** to tes
d750: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 t whether a file
d760: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 is at least rea
d770: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c dable. The fil
d780: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 e can be a.** di
d790: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e rectory..**.** ^
d7a0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 SQLite will alwa
d7b0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c ys allocate at l
d7c0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b east mxPathname+
d7d0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 1 bytes for the.
d7e0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 ** output buffer
d7f0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 xFullPathname.
d800: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 The exact size
d810: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 of the output bu
d820: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 ffer.** is also
d830: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 passed as a para
d840: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d meter to both m
d850: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f ethods. If the o
d860: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 utput buffer.**
d870: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f is not large eno
d880: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e ugh, [SQLITE_CAN
d890: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 TOPEN] should be
d8a0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 returned. Since
d8b0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 this is.** hand
d8c0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 led as a fatal e
d8d0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 rror by SQLite,
d8e0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 vfs implementati
d8f0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 ons should endea
d900: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e vor.** to preven
d910: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e t this by settin
d920: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 g mxPathname to
d930: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c a sufficiently l
d940: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a arge value..**.*
d950: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
d960: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 s(), xSleep(), x
d970: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 CurrentTime(), a
d980: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 nd xCurrentTimeI
d990: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 nt64().** interf
d9a0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 aces are not str
d9b0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 ictly a part of
d9c0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 the filesystem,
d9d0: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 but they are.**
d9e0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 included in the
d9f0: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f VFS structure fo
da00: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a r completeness..
da10: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 ** The xRandomne
da20: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 ss() function at
da30: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e tempts to return
da40: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a nBytes bytes.**
da50: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 of good-quality
da60: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f randomness into
da70: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 zOut. The retu
da80: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 rn value is.** t
da90: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 he actual number
daa0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e of bytes of ran
dab0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 domness obtained
dac0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 ..** The xSleep(
dad0: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 ) method causes
dae0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 the calling thre
daf0: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 ad to sleep for
db00: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 at.** least the
db10: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 number of micros
db20: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e econds given. ^
db30: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 The xCurrentTime
db40: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 ().** method ret
db50: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 urns a Julian Da
db60: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 y Number for the
db70: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e current date an
db80: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 d time as.** a f
db90: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 loating point va
dba0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 lue..** ^The xCu
dbb0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
dbc0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c method returns,
dbd0: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 as an integer,
dbe0: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 the Julian.** Da
dbf0: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c y Number multipl
dc00: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 ied by 86400000
dc10: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d (the number of m
dc20: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a illiseconds in .
dc30: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 ** a 24-hour day
dc40: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ). .** ^SQLite
dc50: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 will use the xCu
dc60: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
dc70: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 method to get t
dc80: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 he current.** da
dc90: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 te and time if t
dca0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 hat method is av
dcb0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 ailable (if iVer
dcc0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a sion is 2 or .**
dcd0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 greater and the
dce0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 function pointe
dcf0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 r is not NULL) a
dd00: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 nd will fall bac
dd10: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 k.** to xCurrent
dd20: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 Time() if xCurre
dd30: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 ntTimeInt64() is
dd40: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a unavailable..**
dd50: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 .** ^The xSetSys
dd60: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 temCall(), xGetS
dd70: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 ystemCall(), and
dd80: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c xNestSystemCall
dd90: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
dda0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 are not used by
ddb0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 the SQLite core
ddc0: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 . These optiona
ddd0: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 l interfaces are
dde0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 provided.** by
ddf0: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 some VFSes to fa
de00: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 cilitate testing
de10: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 of the VFS code
de20: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 . By overriding
de30: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 .** system calls
de40: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 with functions
de50: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f under its contro
de60: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 l, a test progra
de70: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 m can.** simulat
de80: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 e faults and err
de90: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 or conditions th
dea0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 at would otherwi
deb0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a se be difficult.
dec0: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 ** or impossible
ded0: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 to induce. The
dee0: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 set of system c
def0: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 alls that can be
df00: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 overridden.** v
df10: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 aries from one V
df20: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 FS to another, a
df30: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 nd from one vers
df40: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ion of the same
df50: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 VFS to the.** ne
df60: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e xt. Application
df70: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 s that use these
df80: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 interfaces must
df90: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 be prepared for
dfa0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f any.** or all o
dfb0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 f these interfac
dfc0: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 es to be NULL or
dfd0: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 for their behav
dfe0: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a ior to change.**
dff0: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 from one releas
e000: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 e to the next.
e010: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 Applications mus
e020: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f t not attempt to
e030: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f access.** any o
e040: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 f these methods
e050: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 if the iVersion
e060: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 of the VFS is le
e070: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 ss than 3..*/.ty
e080: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
e090: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 ite3_vfs sqlite3
e0a0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f _vfs;.typedef vo
e0b0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 id (*sqlite3_sys
e0c0: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b call_ptr)(void);
e0d0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
e0e0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 vfs {. int iVer
e0f0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 sion;
e100: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 /* Structure ve
e110: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 rsion number (cu
e120: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 rrently 3) */.
e130: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 int szOsFile;
e140: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 /* Size
e150: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 of subclassed s
e160: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 qlite3_file */.
e170: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b int mxPathname;
e180: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
e190: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 imum file pathna
e1a0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 me length */. s
e1b0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 qlite3_vfs *pNex
e1c0: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 t; /* Next
e1d0: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a registered VFS *
e1e0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
e1f0: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 zName; /*
e200: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 Name of this vir
e210: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d tual file system
e220: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 */. void *pApp
e230: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f Data; /
e240: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 * Pointer to app
e250: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 lication-specifi
e260: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 c data */. int
e270: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 (*xOpen)(sqlite3
e280: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
e290: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 r *zName, sqlite
e2a0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 3_file*,.
e2b0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 int flag
e2c0: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 s, int *pOutFlag
e2d0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c s);. int (*xDel
e2e0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ete)(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 73 79 6e 63 44 69 Name, int syncDi
e310: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 r);. int (*xAcc
e320: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
e330: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
e340: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c Name, int flags,
e350: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
e360: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 int (*xFullPat
e370: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 hname)(sqlite3_v
e380: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
e390: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 *zName, int nOut
e3a0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 , char *zOut);.
e3b0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e void *(*xDlOpen
e3c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e3d0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c const char *zFil
e3e0: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 ename);. void (
e3f0: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 *xDlError)(sqlit
e400: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 e3_vfs*, int nBy
e410: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 te, char *zErrMs
e420: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 g);. void (*(*x
e430: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 DlSym)(sqlite3_v
e440: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 fs*,void*, const
e450: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 char *zSymbol))
e460: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 (void);. void (
e470: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 *xDlClose)(sqlit
e480: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b e3_vfs*, void*);
e490: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d . int (*xRandom
e4a0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 ness)(sqlite3_vf
e4b0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
e4c0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e har *zOut);. in
e4d0: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 t (*xSleep)(sqli
e4e0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 te3_vfs*, int mi
e4f0: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 croseconds);. i
e500: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d nt (*xCurrentTim
e510: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
e520: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 double*);. int
e530: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 (*xGetLastError
e540: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e550: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 int, char *);.
e560: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
e570: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
e580: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 version 1 of th
e590: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a e sqlite_vfs obj
e5a0: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 ect. ** definit
e5b0: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 ion. Those that
e5c0: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 follow are adde
e5d0: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f d in version 2 o
e5e0: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 r later. */. i
e5f0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d nt (*xCurrentTim
e600: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f eInt64)(sqlite3_
e610: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e vfs*, sqlite3_in
e620: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a t64*);. /*. **
e630: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f The methods abo
e640: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f ve are in versio
e650: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 ns 1 and 2 of th
e660: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a e sqlite_vfs obj
e670: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 ect.. ** Those
e680: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 below are for ve
e690: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 rsion 3 and grea
e6a0: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 ter.. */. int
e6b0: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c (*xSetSystemCall
e6c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e6d0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
e6e0: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 e, sqlite3_sysca
e6f0: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 ll_ptr);. sqlit
e700: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 e3_syscall_ptr (
e710: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 *xGetSystemCall)
e720: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
e730: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
e740: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 );. const char
e750: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 *(*xNextSystemCa
e760: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ll)(sqlite3_vfs*
e770: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
e780: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 ame);. /*. **
e790: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
e7a0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
e7b0: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 s 1 through 3 of
e7c0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 the sqlite_vfs
e7d0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 object.. ** New
e7e0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
e7f0: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 ppended in figur
e800: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 e versions. The
e810: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 iVersion. ** v
e820: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d alue will increm
e830: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 ent whenever thi
e840: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f s happens. . */
e850: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
e860: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 REF: Flags for t
e870: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d he xAccess VFS m
e880: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ethod.**.** Thes
e890: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
e8a0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 nts can be used
e8b0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 as the third par
e8c0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ameter to.** the
e8d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
e8e0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 of an [sqlite3_v
e8f0: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 fs] object. The
e900: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 y determine.** w
e910: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d hat kind of perm
e920: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 issions the xAcc
e930: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f ess method is lo
e940: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 oking for..** Wi
e950: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
e960: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 _EXISTS, the xAc
e970: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 cess method.** s
e980: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 imply checks whe
e990: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 ther the file ex
e9a0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 ists..** With SQ
e9b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
e9c0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 WRITE, the xAcce
e9d0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
e9e0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
e9f0: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 named directory
ea00: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 is both readable
ea10: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a and writable.**
ea20: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 (in other words
ea30: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 , if files can b
ea40: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 e added, removed
ea50: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 , and renamed wi
ea60: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 thin.** the dire
ea70: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 ctory)..** The S
ea80: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
ea90: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 DWRITE constant
eaa0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 is currently use
eab0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a d only by the.**
eac0: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
ead0: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 ectory pragma],
eae0: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c though this coul
eaf0: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 d change in a fu
eb00: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 ture.** release
eb10: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 of SQLite..** Wi
eb20: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
eb30: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 _READ, the xAcce
eb40: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
eb50: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
eb60: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 file is readable
eb70: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 . The SQLITE_AC
eb80: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 CESS_READ consta
eb90: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 nt is.** current
eba0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 ly unused, thoug
ebb0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 h it might be us
ebc0: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 ed in a future r
ebd0: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c elease of.** SQL
ebe0: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ite..*/.#define
ebf0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
ec00: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e ISTS 0.#defin
ec10: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
ec20: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a READWRITE 1 /*
ec30: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 Used by PRAGMA
ec40: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
ec50: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 tory */.#define
ec60: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
ec70: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 AD 2 /* U
ec80: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 nused */../*.**
ec90: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
eca0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b for the xShmLock
ecb0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a VFS method.**.*
ecc0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
ecd0: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
ece0: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 the various loc
ecf0: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a king operations.
ed00: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 ** allowed by th
ed10: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
ed20: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f d of [sqlite3_io
ed30: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a _methods]. The.
ed40: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 ** following are
ed50: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 the only legal
ed60: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 combinations of
ed70: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 flags to the.**
ed80: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a xShmLock method:
ed90: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
eda0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f li> SQLITE_SHM_
edb0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 LOCK | SQLITE_SH
edc0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e M_SHARED.** <li>
edd0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 SQLITE_SHM_LOC
ede0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 K | SQLITE_SHM_E
edf0: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e XCLUSIVE.** <li>
ee00: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c SQLITE_SHM_UNL
ee10: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
ee20: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 _SHARED.** <li>
ee30: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
ee40: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
ee50: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 EXCLUSIVE.** </u
ee60: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e l>.**.** When un
ee70: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d locking, the sam
ee80: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c e SHARED or EXCL
ee90: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 USIVE flag must
eea0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a be supplied as.*
eeb0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 * was given on t
eec0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
eed0: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 lock. .**.** T
eee0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 he xShmLock meth
eef0: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f od can transitio
ef00: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b n between unlock
ef10: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 ed and SHARED or
ef20: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f .** between unlo
ef30: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 cked and EXCLUSI
ef40: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 VE. It cannot t
ef50: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 ransition betwee
ef60: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 n SHARED.** and
ef70: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 EXCLUSIVE..*/.#d
ef80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
ef90: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a _UNLOCK 1.
efa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
efb0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 HM_LOCK
efc0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
efd0: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 _SHM_SHARED
efe0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
eff0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
f000: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 8../*.** CAP
f010: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 I3REF: Maximum x
f020: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a ShmLock index.**
f030: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b .** The xShmLock
f040: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 method on [sqli
f050: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
f060: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a may use values.*
f070: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 * between 0 and
f080: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 this upper bound
f090: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 as its "offset"
f0a0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 argument..** Th
f0b0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 e SQLite core wi
f0c0: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 ll never attempt
f0d0: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 to acquire or r
f0e0: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b elease a.** lock
f0f0: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 outside of this
f100: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e range.*/.#defin
f110: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f e SQLITE_SHM_NLO
f120: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a CK 8.../*
f130: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
f140: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c itialize The SQL
f150: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a ite Library.**.*
f160: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
f170: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
f180: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 ine initializes
f190: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 the.** SQLite li
f1a0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c brary. ^The sql
f1b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
f1c0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c routine.** deall
f1d0: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 ocates any resou
f1e0: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 rces that were a
f1f0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 llocated by sqli
f200: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
f210: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 ..** These routi
f220: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 nes are designed
f230: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 to aid in proce
f240: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ss initializatio
f250: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 n and.** shutdow
f260: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 n on embedded sy
f270: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 stems. Workstat
f280: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ion applications
f290: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 using.** SQLite
f2a0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 normally do not
f2b0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 need to invoke
f2c0: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 either of these
f2d0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
f2e0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
f2f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
f300: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 s an "effective"
f310: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a call if it is.*
f320: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 * the first time
f330: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
f340: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
f350: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 during the life
f360: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 time of.** the p
f370: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 rocess, or if it
f380: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 is the first ti
f390: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 me sqlite3_initi
f3a0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
f3b0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ed.** following
f3c0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 a call to sqlite
f3d0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 3_shutdown(). ^
f3e0: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 (Only an effecti
f3f0: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 ve call.** of sq
f400: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f410: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 () does any init
f420: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c ialization. All
f430: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 other calls.**
f440: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d are harmless no-
f450: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 ops.)^.**.** A c
f460: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
f470: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 hutdown() is an
f480: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c "effective" call
f490: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 if it is the fi
f4a0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 rst.** call to s
f4b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
f4c0: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 ) since the last
f4d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
f4e0: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a ize(). ^(Only.*
f4f0: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 * an effective c
f500: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
f510: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 hutdown() does a
f520: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 ny deinitializat
f530: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 ion..** All othe
f540: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f r valid calls to
f550: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
f560: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 n() are harmless
f570: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a no-ops.)^.**.**
f580: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 The sqlite3_ini
f590: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 tialize() interf
f5a0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 ace is threadsaf
f5b0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 e, but sqlite3_s
f5c0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 hutdown().** is
f5d0: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 not. The sqlite
f5e0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 3_shutdown() int
f5f0: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 erface must only
f600: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
f610: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 a.** single thre
f620: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 ad. All open [d
f630: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
f640: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f ons] must be clo
f650: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f sed and all.** o
f660: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f ther SQLite reso
f670: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 urces must be de
f680: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 allocated prior
f690: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 to invoking.** s
f6a0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
f6b0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f )..**.** Among o
f6c0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 ther things, ^sq
f6d0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f6e0: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a () will invoke.*
f6f0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
f700: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c t(). Similarly,
f710: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f ^sqlite3_shutdo
f720: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 wn().** will inv
f730: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 oke sqlite3_os_e
f740: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nd()..**.** ^The
f750: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
f760: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ize() routine re
f770: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
f780: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a ] on success..**
f790: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 ^If for some re
f7a0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e ason, sqlite3_in
f7b0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e itialize() is un
f7c0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 able to initiali
f7d0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 ze.** the librar
f7e0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 y (perhaps it is
f7f0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
f800: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 ate a needed res
f810: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 ource such.** as
f820: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 a mutex) it ret
f830: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 urns an [error c
f840: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 ode] other than
f850: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a [SQLITE_OK]..**.
f860: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
f870: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
f880: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 tine is called i
f890: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e nternally by man
f8a0: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 y other.** SQLit
f8b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 e interfaces so
f8c0: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 that an applicat
f8d0: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 ion usually does
f8e0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 not need to.**
f8f0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 invoke sqlite3_i
f900: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 nitialize() dire
f910: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 ctly. For examp
f920: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 le, [sqlite3_ope
f930: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 n()].** calls sq
f940: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f950: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 () so the SQLite
f960: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 library will be
f970: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a automatically.*
f980: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 * initialized wh
f990: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e en [sqlite3_open
f9a0: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 ()] is called if
f9b0: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 it has not be i
f9c0: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c nitialized.** al
f9d0: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 ready. ^However
f9e0: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 , if SQLite is c
f9f0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
fa00: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 [SQLITE_OMIT_AU
fa10: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 TOINIT].** compi
fa20: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 le-time option,
fa30: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 then the automat
fa40: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ic calls to sqli
fa50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
fa60: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 .** are omitted
fa70: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 and the applicat
fa80: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 ion must call sq
fa90: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
faa0: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 () directly.** p
fab0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e rior to using an
fac0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 y other SQLite i
fad0: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d nterface. For m
fae0: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 aximum portabili
faf0: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 ty,.** it is rec
fb00: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
fb10: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 plications alway
fb20: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 s invoke sqlite3
fb30: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a _initialize().**
fb40: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 directly prior
fb50: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
fb60: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
fb70: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c ace. Future rel
fb80: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 eases.** of SQLi
fb90: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 te may require t
fba0: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 his. In other w
fbb0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 ords, the behavi
fbc0: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 or exhibited.**
fbd0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
fbe0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 ompiled with [SQ
fbf0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e LITE_OMIT_AUTOIN
fc00: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 IT] might become
fc10: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 the.** default
fc20: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 behavior in some
fc30: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 future release
fc40: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
fc50: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
fc60: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 init() routine d
fc70: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 oes operating-sy
fc80: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a stem specific.**
fc90: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
fca0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 of the SQLite li
fcb0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 brary. The sqli
fcc0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
fcd0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 routine undoes t
fce0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c he effect of sql
fcf0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
fd00: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a Typical tasks.*
fd10: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 * performed by t
fd20: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e hese routines in
fd30: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e clude allocation
fd40: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e or deallocation
fd50: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 .** of static re
fd60: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c sources, initial
fd70: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 ization of globa
fd80: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 l variables,.**
fd90: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 setting up a def
fda0: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
fdb0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 s] module, or se
fdc0: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 tting up.** a de
fdd0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
fde0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ion using [sqlit
fdf0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a e3_config()]..**
fe00: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
fe10: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
fe20: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 invoke either s
fe30: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
fe40: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f .** or sqlite3_o
fe50: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 s_end() directly
fe60: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 . The applicati
fe70: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 on should only i
fe80: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
fe90: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e _initialize() an
fea0: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f d sqlite3_shutdo
feb0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 wn(). The sqlit
fec0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 e3_os_init().**
fed0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c interface is cal
fee0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c led automaticall
fef0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 y by sqlite3_ini
ff00: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a tialize() and.**
ff10: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
ff20: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 ) is called by s
ff30: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
ff40: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a ). Appropriate.
ff50: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
ff60: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f ns for sqlite3_o
ff70: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
ff80: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
ff90: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 are built into
ffa0: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 SQLite when it i
ffb0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 s compiled for U
ffc0: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 nix, Windows, or
ffd0: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b OS/2..** When [
ffe0: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 custom builds |
fff0: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 built for other
10000 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 platforms].** (u
10010 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
10020 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d _OS_OTHER=1] com
10030 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 pile-time.** opt
10040 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 ion) the applica
10050 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 tion must supply
10060 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c a suitable impl
10070 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a ementation for.*
10080 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
10090 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
100a0 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 os_end(). An ap
100b0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 plication-suppli
100c0 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 ed.** implementa
100d0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
100e0 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c os_init() or sql
100f0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
10100 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 must return [SQ
10110 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
10120 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 ess and some oth
10130 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 er [error code]
10140 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e upon.** failure.
10150 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
10160 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 initialize(void)
10170 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 ;.int sqlite3_sh
10180 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e utdown(void);.in
10190 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 t sqlite3_os_ini
101a0 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c t(void);.int sql
101b0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 ite3_os_end(void
101c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
101d0 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 EF: Configuring
101e0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 The SQLite Libra
101f0 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ry.**.** The sql
10200 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
10210 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
10220 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 to make global c
10230 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 onfiguration.**
10240 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 changes to SQLit
10250 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 e in order to tu
10260 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 ne SQLite to the
10270 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 specific needs
10280 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 of.** the applic
10290 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 ation. The defa
102a0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
102b0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 n is recommended
102c0 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 for most.** app
102d0 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f lications and so
102e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
102f0 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 usually not nec
10300 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a essary. It is.*
10310 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 * provided to su
10320 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 pport rare appli
10330 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 cations with unu
10340 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a sual needs..**.*
10350 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
10360 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
10370 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 is not threadsa
10380 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 fe. The applica
10390 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 tion.** must ins
103a0 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 ure that no othe
103b0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
103c0 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 ces are invoked
103d0 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 by other.** thre
103e0 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 ads while sqlite
103f0 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 3_config() is ru
10400 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d nning. Furtherm
10410 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e ore, sqlite3_con
10420 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c fig().** may onl
10430 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 y be invoked pri
10440 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e or to library in
10450 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 itialization usi
10460 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 ng.** [sqlite3_i
10470 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 nitialize()] or
10480 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 after shutdown b
10490 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 y [sqlite3_shutd
104a0 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 own()]..** ^If s
104b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
104c0 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 is called after
104d0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
104e0 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 ize()] and befor
104f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 e.** [sqlite3_sh
10500 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 utdown()] then i
10510 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 t will return SQ
10520 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 LITE_MISUSE..**
10530 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 Note, however, t
10540 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e hat ^sqlite3_con
10550 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c fig() can be cal
10560 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 led as part of t
10570 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 he.** implementa
10580 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 tion of an appli
10590 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b cation-defined [
105a0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
105b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 )]..**.** The fi
105c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
105d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
105e0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a is an integer.*
105f0 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e * [configuration
10600 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 option] that de
10610 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 termines.** what
10620 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c property of SQL
10630 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e ite is to be con
10640 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 figured. Subseq
10650 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a uent arguments.*
10660 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 * vary depending
10670 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 on the [configu
10680 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a ration option].*
10690 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 * in the first a
106a0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e rgument..**.** ^
106b0 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 When a configura
106c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 tion option is s
106d0 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 et, sqlite3_conf
106e0 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 ig() returns [SQ
106f0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 LITE_OK]..** ^If
10700 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 the option is u
10710 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 nknown or SQLite
10720 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 is unable to se
10730 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 t the option.**
10740 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e then this routin
10750 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d e returns a non-
10760 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
10770 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
10780 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 3_config(int, ..
10790 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
107a0 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 REF: Configure d
107b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
107c0 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ons.** METHOD: s
107d0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 qlite3.**.** The
107e0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
107f0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ig() interface i
10800 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 s used to make c
10810 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 onfiguration.**
10820 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 changes to a [da
10830 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
10840 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 n]. The interfa
10850 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f ce is similar to
10860 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
10870 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 fig()] except th
10880 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 at the changes a
10890 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 pply to a single
108a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
108b0 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 nnection] (speci
108c0 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 fied in the firs
108d0 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a t argument)..**.
108e0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ** The second ar
108f0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
10900 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 3_db_config(D,V,
10910 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 ...) is the.**
10920 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 [SQLITE_DBCONFIG
10930 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e _LOOKASIDE | con
10940 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d figuration verb]
10950 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f - an integer co
10960 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 de .** that indi
10970 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63 cates what aspec
10980 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 t of the [databa
10990 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
109a0 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 s being configur
109b0 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e ed..** Subsequen
109c0 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 t arguments vary
109d0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
109e0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
109f0 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c verb..**.** ^Cal
10a00 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 ls to sqlite3_db
10a10 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e _config() return
10a20 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e SQLITE_OK if an
10a30 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 d only if.** the
10a40 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 call is conside
10a50 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a red successful..
10a60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 */.int sqlite3_d
10a70 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 b_config(sqlite3
10a80 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b *, int op, ...);
10a90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
10aa0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
10ab0 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a ion Routines.**.
10ac0 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
10ad0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 f this object de
10ae0 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 fines the interf
10af0 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 ace between SQLi
10b00 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 te.** and low-le
10b10 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 vel memory alloc
10b20 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a ation routines..
10b30 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 **.** This objec
10b40 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c t is used in onl
10b50 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 y one place in t
10b60 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 he SQLite interf
10b70 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 ace..** A pointe
10b80 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
10b90 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
10ba0 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 is the argument
10bb0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
10bc0 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 onfig()] when th
10bd0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
10be0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 option is.** [SQ
10bf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
10c00 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 OC] or [SQLITE_C
10c10 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d ONFIG_GETMALLOC]
10c20 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 . .** By creati
10c30 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f ng an instance o
10c40 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a f this object.**
10c50 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 and passing it
10c60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to [sqlite3_conf
10c70 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ig]([SQLITE_CONF
10c80 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 IG_MALLOC]).** d
10c90 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 uring configurat
10ca0 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 ion, an applicat
10cb0 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 ion can specify
10cc0 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a an alternative.*
10cd0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
10ce0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f ion subsystem fo
10cf0 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 r SQLite to use
10d00 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a for all of its.*
10d10 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 * dynamic memory
10d20 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f needs..**.** No
10d30 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 te that SQLite c
10d40 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 omes with severa
10d50 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f l [built-in memo
10d60 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a ry allocators].*
10d70 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 * that are perfe
10d80 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f ctly adequate fo
10d90 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 r the overwhelmi
10da0 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 ng majority of a
10db0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 pplications.** a
10dc0 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a nd that this obj
10dd0 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 ect is only usef
10de0 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e ul to a tiny min
10df0 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 ority of applica
10e00 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 tions.** with sp
10e10 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 ecialized memory
10e20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 allocation requ
10e30 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 irements. This
10e40 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 object is.** als
10e50 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 o used during te
10e60 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 sting of SQLite
10e70 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 in order to spec
10e80 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 ify an alternati
10e90 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c ve.** memory all
10ea0 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 ocator that simu
10eb0 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 lates memory out
10ec0 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 -of-memory condi
10ed0 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 tions in.** orde
10ee0 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 r to verify that
10ef0 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 SQLite recovers
10f00 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d gracefully from
10f10 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 such.** conditi
10f20 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ons..**.** The x
10f30 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 Malloc, xRealloc
10f40 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 , and xFree meth
10f50 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 ods must work li
10f60 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 ke the.** malloc
10f70 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e (), realloc() an
10f80 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f d free() functio
10f90 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ns from the stan
10fa0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
10fb0 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 ** ^SQLite guara
10fc0 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 ntees that the s
10fd0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
10fe0 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 o.** xRealloc is
10ff0 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 always a value
11000 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 returned by a pr
11010 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 ior call to xRou
11020 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a ndup..**.** xSiz
11030 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 e should return
11040 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 the allocated si
11050 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 ze of a memory a
11060 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 llocation.** pre
11070 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 viously obtained
11080 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 from xMalloc or
11090 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 xRealloc. The
110a0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a allocated size.*
110b0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c * is always at l
110c0 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 east as big as t
110d0 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a he requested siz
110e0 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 e but may be lar
110f0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ger..**.** The x
11100 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 Roundup method r
11110 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c eturns what woul
11120 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 d be the allocat
11130 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 ed size of.** a
11140 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
11150 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 n given a partic
11160 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 ular requested s
11170 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 ize. Most memor
11180 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 y.** allocators
11190 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 round up memory
111a0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c allocations at l
111b0 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 east to the next
111c0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 multiple.** of
111d0 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 8. Some allocat
111e0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 ors round up to
111f0 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c a larger multipl
11200 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 e or to a power
11210 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d of 2..** Every m
11220 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
11230 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 request coming
11240 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 in through [sqli
11250 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a te3_malloc()].**
11260 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
11270 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 lloc()] first ca
11280 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 lls xRoundup. I
11290 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 f xRoundup retur
112a0 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 ns 0, .** that c
112b0 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 auses the corres
112c0 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 ponding memory a
112d0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 llocation to fai
112e0 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e l..**.** The xIn
112f0 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 it method initia
11300 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 lizes the memory
11310 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 allocator. For
11320 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 example,.** it
11330 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 might allocate a
11340 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 ny require mutex
11350 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 es or initialize
11360 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a internal data.*
11370 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 * structures. T
11380 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 he xShutdown met
11390 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 hod is invoked (
113a0 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a indirectly) by.*
113b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 * [sqlite3_shutd
113c0 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c own()] and shoul
113d0 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 d deallocate any
113e0 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 resources acqui
113f0 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e red.** by xInit.
11400 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 The pAppData p
11410 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 ointer is used a
11420 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d s the only param
11430 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 eter to.** xInit
11440 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a and xShutdown..
11450 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c **.** SQLite hol
11460 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d ds the [SQLITE_M
11470 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 UTEX_STATIC_MAST
11480 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 ER] mutex when i
11490 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 t invokes.** the
114a0 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 xInit method, s
114b0 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 o the xInit meth
114c0 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 od need not be t
114d0 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a hreadsafe. The.
114e0 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 ** xShutdown met
114f0 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c hod is only call
11500 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
11510 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 _shutdown()] so
11520 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e it does.** not n
11530 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 eed to be thread
11540 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f safe either. Fo
11550 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 r all other meth
11560 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 ods, SQLite.** h
11570 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 olds the [SQLITE
11580 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 _MUTEX_STATIC_ME
11590 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 M] mutex as long
115a0 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 as the.** [SQLI
115b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
115c0 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 TUS] configurati
115d0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 on option is tur
115e0 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a ned on (which.**
115f0 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c it is by defaul
11600 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 t) and so the me
11610 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 thods are automa
11620 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a tically serializ
11630 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 ed..** However,
11640 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 if [SQLITE_CONFI
11650 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 G_MEMSTATUS] is
11660 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 disabled, then t
11670 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 he other.** meth
11680 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 ods must be thre
11690 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d adsafe or else m
116a0 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 ake their own ar
116b0 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a rangements for.*
116c0 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e * serialization.
116d0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 .**.** SQLite wi
116e0 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 ll never invoke
116f0 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 xInit() more tha
11700 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 n once without a
11710 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a n intervening.**
11720 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f call to xShutdo
11730 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 wn()..*/.typedef
11740 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
11750 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 mem_methods sqli
11760 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b te3_mem_methods;
11770 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
11780 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 mem_methods {.
11790 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 void *(*xMalloc)
117a0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f (int); /
117b0 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * Memory allocat
117c0 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a ion function */.
117d0 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 void (*xFree)(
117e0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 void*);
117f0 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 /* Free a prior
11800 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
11810 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f void *(*xReallo
11820 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 c)(void*,int);
11830 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c /* Resize an all
11840 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 ocation */. int
11850 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 (*xSize)(void*)
11860 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 ; /* R
11870 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f eturn the size o
11880 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 f an allocation
11890 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e */. int (*xRoun
118a0 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 dup)(int);
118b0 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 /* Round up
118c0 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 request size to
118d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 allocation size
118e0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 */. int (*xInit
118f0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
11900 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a /* Initializ
11910 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
11920 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 ocator */. void
11930 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f (*xShutdown)(vo
11940 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 id*); /* De
11950 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d initialize the m
11960 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
11970 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
11980 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 ata;
11990 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 /* Argument
119a0 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 to xInit() and x
119b0 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b Shutdown() */.};
119c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
119d0 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 : Configuration
119e0 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f Options.** KEYWO
119f0 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 RDS: {configurat
11a00 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a ion option}.**.*
11a10 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
11a20 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 s are the availa
11a30 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 ble integer conf
11a40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
11a50 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 s that.** can be
11a60 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
11a70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
11a80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
11a90 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
11aa0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e e..**.** New con
11ab0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
11ac0 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ns may be added
11ad0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
11ae0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
11af0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 Existing config
11b00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
11b10 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 might be discont
11b20 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 inued. Applicat
11b30 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 ions.** should c
11b40 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
11b50 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 code from [sqlit
11b60 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 e3_config()] to
11b70 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a make sure that.*
11b80 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 * the call worke
11b90 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 d. The [sqlite3
11ba0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
11bb0 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e face will return
11bc0 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b a.** non-zero [
11bd0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 error code] if a
11be0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 discontinued or
11bf0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e unsupported con
11c00 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
11c10 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e n.** is invoked.
11c20 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b .**.** <dl>.** [
11c30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
11c40 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 INGLETHREAD]] <d
11c50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
11c60 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 SINGLETHREAD</dt
11c70 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
11c80 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
11c90 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
11ca0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
11cb0 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
11cc0 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 ding mode] to Si
11cd0 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e ngle-thread. In
11ce0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 other words, it
11cf0 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c disables.** all
11d00 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 mutexing and pu
11d10 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 ts SQLite into a
11d20 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 mode where it c
11d30 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a an only be used.
11d40 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 ** by a single t
11d50 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c hread. ^If SQL
11d60 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
11d70 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
11d80 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
11d90 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
11da0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
11db0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
11dc0 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 * it is not poss
11dd0 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 ible to change t
11de0 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f he [threading mo
11df0 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 de] from its def
11e00 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 ault.** value of
11e10 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 Single-thread a
11e20 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 nd so [sqlite3_c
11e30 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 onfig()] will re
11e40 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 turn .** [SQLITE
11e50 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 _ERROR] if calle
11e60 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 d with the SQLIT
11e70 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
11e80 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 HREAD.** configu
11e90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
11ea0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
11eb0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
11ec0 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 HREAD]] <dt>SQLI
11ed0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
11ee0 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 HREAD</dt>.** <d
11ef0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 d>There are no a
11f00 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
11f10 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 option. ^This
11f20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a option sets the.
11f30 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ** [threading mo
11f40 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 de] to Multi-thr
11f50 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 ead. In other w
11f60 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 ords, it disable
11f70 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e s.** mutexing on
11f80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
11f90 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 ction] and [prep
11fa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
11fb0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 objects..** The
11fc0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 application is r
11fd0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 esponsible for s
11fe0 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 erializing acces
11ff0 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 s to.** [databas
12000 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 e connections] a
12010 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
12020 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f tements]. But o
12030 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 ther mutexes.**
12040 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 are enabled so t
12050 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
12060 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 be safe to use i
12070 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 n a multi-thread
12080 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e ed.** environmen
12090 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 t as long as no
120a0 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 two threads atte
120b0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 mpt to use the s
120c0 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 ame.** [database
120d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 connection] at
120e0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 the same time.
120f0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
12100 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
12110 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
12120 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
12130 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
12140 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
12150 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e then.** it is n
12160 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 ot possible to s
12170 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 et the Multi-thr
12180 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d ead [threading m
12190 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ode] and.** [sql
121a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
121b0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
121c0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c TE_ERROR] if cal
121d0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
121e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
121f0 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 LTITHREAD config
12200 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c uration option.<
12210 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
12220 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
12230 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 LIZED]] <dt>SQLI
12240 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
12250 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 IZED</dt>.** <dd
12260 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
12270 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
12280 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f option. ^This o
12290 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
122a0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 * [threading mod
122b0 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 e] to Serialized
122c0 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 . In other words
122d0 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e , this option en
122e0 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 ables.** all mut
122f0 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 exes including t
12300 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 he recursive.**
12310 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 mutexes on [data
12320 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
12330 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
12340 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 tatement] object
12350 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f s..** In this mo
12360 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 de (which is the
12370 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 default when SQ
12380 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
12390 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 with.** [SQLITE
123a0 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 _THREADSAFE=1])
123b0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
123c0 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 ry will itself s
123d0 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a erialize access.
123e0 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 ** to [database
123f0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 connections] and
12400 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
12410 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 ments] so that t
12420 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f he.** applicatio
12430 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 n is free to use
12440 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
12450 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
12460 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b or the.** same [
12470 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
12480 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 nt] in different
12490 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 threads at the
124a0 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 same time..** ^I
124b0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
124c0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
124d0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
124e0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
124f0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
12500 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
12510 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 hen.** it is not
12520 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 possible to set
12530 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 the Serialized
12540 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
12550 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
12560 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 _config()] will
12570 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
12580 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 RROR] if called
12590 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 with the.** SQLI
125a0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
125b0 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 IZED configurati
125c0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a on option.</dd>.
125d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
125e0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c ONFIG_MALLOC]] <
125f0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
12600 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 _MALLOC</dt>.**
12610 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 <dd> ^(The SQLIT
12620 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 E_CONFIG_MALLOC
12630 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
12640 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
12650 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f hich is .** a po
12660 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
12670 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
12680 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
12690 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 ] structure..**
126a0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 The argument spe
126b0 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e cifies.** altern
126c0 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 ative low-level
126d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
126e0 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 n routines to be
126f0 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f used in place o
12700 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 f.** the memory
12710 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
12720 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 nes built into S
12730 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 QLite.)^ ^SQLite
12740 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 makes.** its ow
12750 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f n private copy o
12760 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 f the content of
12770 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 the [sqlite3_me
12780 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 m_methods] struc
12790 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 ture.** before t
127a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 he [sqlite3_conf
127b0 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 ig()] call retur
127c0 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ns.</dd>.**.** [
127d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
127e0 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 ETMALLOC]] <dt>S
127f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
12800 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
12810 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 dd> ^(The SQLITE
12820 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
12830 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 C option takes a
12840 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
12850 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 which.** is a p
12860 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
12870 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 tance of the [sq
12880 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
12890 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a s] structure..**
128a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 The [sqlite3_me
128b0 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 m_methods].** st
128c0 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 ructure is fille
128d0 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 d with the curre
128e0 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d ntly defined mem
128f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
12900 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 outines.)^.** Th
12910 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 is option can be
12920 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 used to overloa
12930 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 d the default me
12940 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
12950 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 ** routines with
12960 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 a wrapper that
12970 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f simulations memo
12980 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
12990 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 ilure or.** trac
129a0 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c ks memory usage,
129b0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f for example. </
129c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
129d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
129e0 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 TUS]] <dt>SQLITE
129f0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
12a00 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e S</dt>.** <dd> ^
12a10 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
12a20 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 G_MEMSTATUS opti
12a30 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 on takes single
12a40 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 argument of type
12a50 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 int,.** interpr
12a60 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 eted as a boolea
12a70 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 n, which enables
12a80 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 or disables the
12a90 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a collection of.*
12aa0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
12ab0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 ion statistics.
12ac0 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c ^(When memory al
12ad0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 location statist
12ae0 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 ics are.** disab
12af0 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 led, the followi
12b00 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ng SQLite interf
12b10 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d aces become non-
12b20 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 operational:.**
12b30 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e <ul>.** <li>
12b40 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
12b50 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c _used()].** <l
12b60 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f i> [sqlite3_memo
12b70 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a ry_highwater()].
12b80 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
12b90 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
12ba0 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 it64()].** <li
12bb0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 > [sqlite3_statu
12bc0 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c s64()].** </ul
12bd0 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 >)^.** ^Memory a
12be0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 llocation statis
12bf0 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 tics are enabled
12c00 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 by default unle
12c10 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 ss SQLite is.**
12c20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 compiled with [S
12c30 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 QLITE_DEFAULT_ME
12c40 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 MSTATUS]=0 in wh
12c50 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a ich case memory.
12c60 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 ** allocation st
12c70 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 atistics are dis
12c80 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
12c90 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
12ca0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
12cb0 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 _SCRATCH]] <dt>S
12cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
12cd0 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATCH</dt>.** <dd
12ce0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f > ^The SQLITE_CO
12cf0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 NFIG_SCRATCH opt
12d00 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
12d10 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
12d20 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c ffer.** that SQL
12d30 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 ite can use for
12d40 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 scratch memory.
12d50 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 ^(There are thr
12d60 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 ee arguments.**
12d70 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 to SQLITE_CONFIG
12d80 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 _SCRATCH: A poi
12d90 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a nter an 8-byte.*
12da0 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 * aligned memory
12db0 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 buffer from whi
12dc0 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 ch the scratch a
12dd0 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 llocations will
12de0 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 be.** drawn, the
12df0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 size of each sc
12e00 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e ratch allocation
12e10 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 (sz),.** and th
12e20 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
12e30 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f of scratch allo
12e40 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a cations (N).)^.*
12e50 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
12e60 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 ment must be a p
12e70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 ointer to an 8-b
12e80 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 yte aligned buff
12e90 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 er.** of at leas
12ea0 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
12eb0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 memory..** ^SQLi
12ec0 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 te will not use
12ed0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 more than one sc
12ee0 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 ratch buffers pe
12ef0 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 r thread..** ^SQ
12f00 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 Lite will never
12f10 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 request a scratc
12f20 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 h buffer that is
12f30 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 more than 6.**
12f40 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 times the databa
12f50 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a se page size..**
12f60 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 ^If SQLite need
12f70 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e s needs addition
12f80 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 al.** scratch me
12f90 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 mory beyond what
12fa0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 is provided by
12fb0 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 this configurati
12fc0 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 on option, then
12fd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
12fe0 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 loc()] will be u
12ff0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 sed to obtain th
13000 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e e memory needed.
13010 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 <p>.** ^When the
13020 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f application pro
13030 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 vides any amount
13040 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f of scratch memo
13050 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 ry using.** SQLI
13060 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
13070 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 H, SQLite avoids
13080 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 unnecessary lar
13090 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d ge.** [sqlite3_m
130a0 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 alloc|heap alloc
130b0 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 ations]..** This
130c0 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f can help [Robso
130d0 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 n proof|prevent
130e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
130f0 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 n failures] due
13100 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d to heap.** fragm
13110 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d entation in low-
13120 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 memory embedded
13130 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 systems..** </dd
13140 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
13150 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
13160 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 E]] <dt>SQLITE_C
13170 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c ONFIG_PAGECACHE<
13180 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
13190 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
131a0 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e PAGECACHE option
131b0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
131c0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
131d0 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 r.** that SQLite
131e0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 can use for the
131f0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 database page c
13200 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 ache with the de
13210 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 fault page.** ca
13220 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
13230 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f on. .** This co
13240 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 nfiguration shou
13250 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 ld not be used i
13260 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
13270 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 -define page.**
13280 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
13290 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 tion is loaded u
132a0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
132b0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d _CONFIG_PCACHE2]
132c0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f .** configuratio
132d0 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 n option..** ^Th
132e0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
132f0 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 guments to SQLIT
13300 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
13310 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f HE: A pointer to
13320 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e .** 8-byte align
13330 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 ed.** memory, th
13340 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 e size of each p
13350 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c age buffer (sz),
13360 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 and the number
13370 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a of pages (N)..**
13380 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 The sz argument
13390 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 should be the s
133a0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 ize of the large
133b0 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 st database page
133c0 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 .** (a power of
133d0 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 two between 512
133e0 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 and 65536) plus
133f0 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 some extra bytes
13400 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 for each.** pag
13410 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 e header. ^The
13420 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 number of extra
13430 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 bytes needed by
13440 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a the page header.
13450 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d ** can be determ
13460 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b ined using the [
13470 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
13480 41 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 ACHE_HDRSZ] opti
13490 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 on .** to [sqlit
134a0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a e3_config()]..**
134b0 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 ^It is harmless
134c0 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 , apart from the
134d0 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a wasted memory,.
134e0 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 ** for the sz pa
134f0 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 rameter to be la
13500 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 rger than necess
13510 61 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a ary. The first.
13520 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 ** argument shou
13530 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e ld pointer to an
13540 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 8-byte aligned
13550 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 block of memory
13560 74 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 that.** is at le
13570 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f ast sz*N bytes o
13580 66 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 f memory, otherw
13590 69 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62 ise subsequent b
135a0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e ehavior is.** un
135b0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c defined..** ^SQL
135c0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 ite will use the
135d0 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 memory provided
135e0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 by the first ar
135f0 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 gument to satisf
13600 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 y its.** memory
13610 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 needs for the fi
13620 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 rst N pages that
13630 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 it adds to cach
13640 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e e. ^If addition
13650 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 al.** page cache
13660 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 memory is neede
13670 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 d beyond what is
13680 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 provided by thi
13690 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a s option, then.*
136a0 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f * SQLite goes to
136b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
136c0 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 ()] for the addi
136d0 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 tional storage s
136e0 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a pace.</dd>.**.**
136f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
13700 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 _HEAP]] <dt>SQLI
13710 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f TE_CONFIG_HEAP</
13720 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 dt>.** <dd> ^The
13730 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 SQLITE_CONFIG_H
13740 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 EAP option speci
13750 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
13760 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 mory buffer .**
13770 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
13780 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 use for all of
13790 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f its dynamic memo
137a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
137b0 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 eds.** beyond th
137c0 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 ose provided for
137d0 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 by [SQLITE_CONF
137e0 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a IG_SCRATCH] and.
137f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
13800 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a G_PAGECACHE]..**
13810 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^The SQLITE_CON
13820 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 FIG_HEAP option
13830 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c is only availabl
13840 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 e if SQLite is c
13850 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 ompiled.** with
13860 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 either [SQLITE_E
13870 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f NABLE_MEMSYS3] o
13880 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 r [SQLITE_ENABLE
13890 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 _MEMSYS5] and re
138a0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 turns.** [SQLITE
138b0 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b _ERROR] if invok
138c0 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a ed otherwise..**
138d0 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 ^There are thre
138e0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 e arguments to S
138f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
13900 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 P:.** An 8-byte
13910 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 aligned pointer
13920 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a to the memory,.*
13930 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
13940 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d bytes in the mem
13950 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 ory buffer, and
13960 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f the minimum allo
13970 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 cation size..**
13980 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f ^If the first po
13990 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 inter (the memor
139a0 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 y pointer) is NU
139b0 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 LL, then SQLite
139c0 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 reverts.** to us
139d0 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 ing its default
139e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
139f0 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c (the system mal
13a00 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 loc() implementa
13a10 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e tion),.** undoin
13a20 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f g any prior invo
13a30 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 cation of [SQLIT
13a40 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
13a50 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 . ^If the.** me
13a60 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 mory pointer is
13a70 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 not NULL then th
13a80 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 e alternative me
13a90 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
13aa0 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 r is engaged to
13ab0 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 handle all of SQ
13ac0 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c Lites memory all
13ad0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a ocation needs..*
13ae0 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e * The first poin
13af0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 ter (the memory
13b00 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 pointer) must be
13b10 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 aligned to an 8
13b20 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 -byte.** boundar
13b30 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 y or subsequent
13b40 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 behavior of SQLi
13b50 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 te will be undef
13b60 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e ined..** The min
13b70 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 imum allocation
13b80 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 size is capped a
13b90 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 t 2**12. Reasona
13ba0 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f ble values.** fo
13bb0 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c r the minimum al
13bc0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 location size ar
13bd0 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 e 2**5 through 2
13be0 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 **8.</dd>.**.**
13bf0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
13c00 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 MUTEX]] <dt>SQLI
13c10 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c TE_CONFIG_MUTEX<
13c20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
13c30 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
13c40 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 _MUTEX option ta
13c50 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
13c60 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
13c70 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 .** pointer to a
13c80 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
13c90 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
13ca0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
13cb0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 ure..** The argu
13cc0 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 ment specifies a
13cd0 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c lternative low-l
13ce0 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 evel mutex routi
13cf0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a nes to be used.*
13d00 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d * in place the m
13d10 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 utex routines bu
13d20 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e ilt into SQLite.
13d30 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 )^ ^SQLite make
13d40 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 s a copy of.** t
13d50 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
13d60 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
13d70 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
13d80 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 ure before the c
13d90 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
13da0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 e3_config()] ret
13db0 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 urns. ^If SQLite
13dc0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
13dd0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
13de0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
13df0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
13e00 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
13e10 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 option then.** t
13e20 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 he entire mutexi
13e30 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 ng subsystem is
13e40 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 omitted from the
13e50 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 build and hence
13e60 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 calls to.** [sq
13e70 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
13e80 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
13e90 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e CONFIG_MUTEX con
13ea0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
13eb0 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e n will.** return
13ec0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e [SQLITE_ERROR].
13ed0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
13ee0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
13ef0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 UTEX]] <dt>SQLIT
13f00 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
13f10 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e X</dt>.** <dd> ^
13f20 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
13f30 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 IG_GETMUTEX opti
13f40 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
13f50 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
13f60 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 .** is a pointer
13f70 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
13f80 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
13f90 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
13fa0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a tructure. The.*
13fb0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 * [sqlite3_mutex
13fc0 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
13fd0 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
13fe0 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
13ff0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 tly defined mute
14000 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a x routines.)^.**
14010 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
14020 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
14030 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
14040 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f mutex allocatio
14050 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 n.** routines wi
14060 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 th a wrapper use
14070 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 d to track mutex
14080 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f usage for perfo
14090 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c rmance.** profil
140a0 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 ing or testing,
140b0 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e for example. ^
140c0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
140d0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
140e0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
140f0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
14100 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
14110 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
14120 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 then.** the enti
14130 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 re mutexing subs
14140 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 ystem is omitted
14150 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 from the build
14160 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 and hence calls
14170 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
14180 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 onfig()] with th
14190 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
141a0 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 GETMUTEX configu
141b0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 ration option wi
141c0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
141d0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 LITE_ERROR].</dd
141e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
141f0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
14200 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 E]] <dt>SQLITE_C
14210 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c ONFIG_LOOKASIDE<
14220 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
14230 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
14240 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f _LOOKASIDE optio
14250 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 n takes two argu
14260 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 ments that deter
14270 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 mine.** the defa
14280 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b ult size of look
14290 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 aside memory on
142a0 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 each [database c
142b0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 onnection]..** T
142c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
142d0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 t is the.** size
142e0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 of each lookasi
142f0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 de buffer slot a
14300 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 nd the second is
14310 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
14320 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 * slots allocate
14330 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 d to each databa
14340 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e se connection.)^
14350 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ^(SQLITE_CONFI
14360 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 G_LOOKASIDE.** s
14370 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 ets the <i>defau
14380 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 lt</i> lookaside
14390 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 size. The [SQLI
143a0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
143b0 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e ASIDE].** option
143c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f to [sqlite3_db_
143d0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 config()] can be
143e0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 used to change
143f0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a the lookaside.**
14400 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
14410 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e n individual con
14420 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 nections.)^ </dd
14430 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
14440 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d _CONFIG_PCACHE2]
14450 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
14460 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e FIG_PCACHE2</dt>
14470 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
14480 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
14490 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 CHE2 option take
144a0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
144b0 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a ent which is .**
144c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
144d0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
144e0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 _methods2] objec
144f0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 t. This object
14500 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 specifies.** the
14510 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 interface to a
14520 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 custom page cach
14530 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
14540 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d .)^.** ^SQLite m
14550 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 akes a copy of t
14560 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 he [sqlite3_pcac
14570 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a he_methods2] obj
14580 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ect.</dd>.**.**
14590 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
145a0 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 GETPCACHE2]] <dt
145b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
145c0 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a ETPCACHE2</dt>.*
145d0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
145e0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
145f0 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b ACHE2 option tak
14600 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
14610 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 ment which.** is
14620 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
14630 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
14640 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 _methods2] objec
14650 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 t. SQLite copie
14660 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 s of.** the curr
14670 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 ent page cache i
14680 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e mplementation in
14690 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 to that object.)
146a0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b ^ </dd>.**.** [[
146b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
146c0 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 G]] <dt>SQLITE_C
146d0 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a ONFIG_LOG</dt>.*
146e0 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 * <dd> The SQLIT
146f0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 E_CONFIG_LOG opt
14700 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 ion is used to c
14710 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c onfigure the SQL
14720 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 ite.** global [e
14730 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e rror log]..** (^
14740 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
14750 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b G_LOG option tak
14760 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 es two arguments
14770 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 : a pointer to a
14780 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 .** function wit
14790 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 h a call signatu
147a0 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f re of void(*)(vo
147b0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 id*,int,const ch
147c0 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 ar*), .** and a
147d0 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e pointer to void.
147e0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f ^If the functio
147f0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 n pointer is not
14800 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 NULL, it is.**
14810 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 invoked by [sqli
14820 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 te3_log()] to pr
14830 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 ocess each loggi
14840 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 ng event. ^If t
14850 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 he.** function p
14860 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 ointer is NULL,
14870 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 the [sqlite3_log
14880 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 ()] interface be
14890 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a comes a no-op..*
148a0 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e * ^The void poin
148b0 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 ter that is the
148c0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
148d0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 to SQLITE_CONFIG
148e0 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 _LOG is.** passe
148f0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 d through as the
14900 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
14910 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 to the applicat
14920 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 ion-defined logg
14930 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 er.** function w
14940 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e henever that fun
14950 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 ction is invoked
14960 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 . ^The second p
14970 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 arameter to.** t
14980 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 he logger functi
14990 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 on is a copy of
149a0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
149b0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 ter to the corre
149c0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c sponding.** [sql
149d0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c ite3_log()] call
149e0 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 and is intended
149f0 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 to be a [result
14a00 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 code] or an.**
14a10 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
14a20 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 code]. ^The th
14a30 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 ird parameter pa
14a40 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 ssed to the logg
14a50 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 er is.** log mes
14a60 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 sage after forma
14a70 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 tting via [sqlit
14a80 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a e3_snprintf()]..
14a90 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f ** The SQLite lo
14aa0 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 gging interface
14ab0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 is not reentrant
14ac0 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e ; the logger fun
14ad0 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 ction.** supplie
14ae0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 d by the applica
14af0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e tion must not in
14b00 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 voke any SQLite
14b10 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e interface..** In
14b20 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 a multi-threade
14b30 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 d application, t
14b40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
14b50 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a efined logger.**
14b60 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 function must b
14b70 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f e threadsafe. </
14b80 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
14b90 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 TE_CONFIG_URI]]
14ba0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
14bb0 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 G_URI.** <dd>^(T
14bc0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
14bd0 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 _URI option take
14be0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
14bf0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e ent of type int.
14c00 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c .** If non-zero,
14c10 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 then URI handli
14c20 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 ng is globally e
14c30 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 nabled. If the p
14c40 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f arameter is zero
14c50 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 ,.** then URI ha
14c60 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c ndling is global
14c70 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e ly disabled.)^ ^
14c80 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 If URI handling
14c90 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 is globally.** e
14ca0 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 nabled, all file
14cb0 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 names passed to
14cc0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
14cd0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f , [sqlite3_open_
14ce0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 v2()],.** [sqlit
14cf0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a e3_open16()] or.
14d00 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 ** specified as
14d10 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d part of [ATTACH]
14d20 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e commands are in
14d30 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 terpreted as URI
14d40 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a s, regardless.**
14d50 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
14d60 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f ot the [SQLITE_O
14d70 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 PEN_URI] flag is
14d80 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 set when the da
14d90 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
14da0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 tion is opened.
14db0 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c ^If it is global
14dc0 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c ly disabled, fil
14dd0 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e enames are.** on
14de0 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 ly interpreted a
14df0 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 s URIs if the SQ
14e00 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c LITE_OPEN_URI fl
14e10 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 ag is set when t
14e20 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 he.** database c
14e30 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 onnection is ope
14e40 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c ned. ^(By defaul
14e50 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 t, URI handling
14e60 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 is globally.** d
14e70 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 isabled. The def
14e80 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 ault value may b
14e90 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d e changed by com
14ea0 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a piling with the.
14eb0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 ** [SQLITE_USE_U
14ec0 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e RI] symbol defin
14ed0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 ed.)^.**.** [[SQ
14ee0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 LITE_CONFIG_COVE
14ef0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d RING_INDEX_SCAN]
14f00 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
14f10 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 FIG_COVERING_IND
14f20 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e EX_SCAN.** <dd>^
14f30 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
14f40 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 G_COVERING_INDEX
14f50 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b _SCAN option tak
14f60 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 es a single inte
14f70 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ger.** argument
14f80 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 which is interpr
14f90 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 eted as a boolea
14fa0 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e n in order to en
14fb0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a able or disable.
14fc0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f ** the use of co
14fd0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 vering indices f
14fe0 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 or full table sc
14ff0 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 ans in the query
15000 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e optimizer..** ^
15010 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 The default sett
15020 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 ing is determine
15030 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c d.** by the [SQL
15040 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 ITE_ALLOW_COVERI
15050 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 NG_INDEX_SCAN] c
15060 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
15070 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a on, or is "on".*
15080 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c * if that compil
15090 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 e-time option is
150a0 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 omitted..** The
150b0 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 ability to disa
150c0 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 ble the use of c
150d0 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 overing indices
150e0 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 for full table s
150f0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 cans.** is becau
15100 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 se some incorrec
15110 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 tly coded legacy
15120 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 applications mi
15130 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a ght malfunction.
15140 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 ** when the opti
15150 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 mization is enab
15160 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 led. Providing
15170 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a the ability to.*
15180 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 * disable the op
15190 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 timization allow
151a0 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 s the older, bug
151b0 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 gy application c
151c0 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 ode to work.** w
151d0 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 ithout change ev
151e0 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 en with newer ve
151f0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
15200 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ..**.** [[SQLITE
15210 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d _CONFIG_PCACHE]]
15220 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
15230 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 _GETPCACHE]].**
15240 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
15250 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c G_PCACHE and SQL
15260 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
15270 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 ACHE.** <dd> The
15280 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f se options are o
15290 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 bsolete and shou
152a0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 ld not be used b
152b0 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 y new code..** T
152c0 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 hey are retained
152d0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 for backwards c
152e0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 ompatibility but
152f0 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e are now no-ops.
15300 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
15310 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
15320 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e SQLLOG]].** <dt>
15330 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 SQLITE_CONFIG_SQ
15340 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 LLOG.** <dd>This
15350 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 option is only
15360 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c available if sql
15370 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
15380 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c with the.** [SQL
15390 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f ITE_ENABLE_SQLLO
153a0 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 G] pre-processor
153b0 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 macro defined.
153c0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
153d0 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 nt should.** be
153e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 a pointer to a f
153f0 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 unction of type
15400 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
15410 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 lite3*,const cha
15420 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 r*, int)..** The
15430 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 second should b
15440 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a e of type (void*
15450 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 ). The callback
15460 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 is invoked by th
15470 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 e library.** in
15480 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 three separate c
15490 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 ircumstances, id
154a0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 entified by the
154b0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
154c0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 the.** fourth pa
154d0 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 rameter. If the
154e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
154f0 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 is 0, then the
15500 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
15510 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 ion.** passed as
15520 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
15530 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 ment has just be
15540 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 en opened. The t
15550 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a hird argument.**
15560 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 points to a buf
15570 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 fer containing t
15580 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d he name of the m
15590 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c ain database fil
155a0 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 e. If the.** fou
155b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
155c0 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 1, then the SQL
155d0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
155e0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
155f0 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f ter.** points to
15600 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 has just been e
15610 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 xecuted. Or, if
15620 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
15630 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a eter is 2, then.
15640 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f ** the connectio
15650 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 n being passed a
15660 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
15670 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 ameter is being
15680 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 closed. The.** t
15690 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 hird parameter i
156a0 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e s passed NULL In
156b0 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 this case. An
156c0 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 example of using
156d0 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 this.** configu
156e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 ration option ca
156f0 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 n be seen in the
15700 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 "test_sqllog.c"
15710 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a source file in.
15720 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c ** the canonical
15730 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 SQLite source t
15740 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ree.</dd>.**.**
15750 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
15760 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c MMAP_SIZE]].** <
15770 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
15780 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 _MMAP_SIZE.** <d
15790 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 d>^SQLITE_CONFIG
157a0 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 _MMAP_SIZE takes
157b0 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 two 64-bit inte
157c0 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 ger (sqlite3_int
157d0 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 64) values.** th
157e0 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 at are the defau
157f0 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d lt mmap size lim
15800 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 it (the default
15810 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b setting for.** [
15820 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 PRAGMA mmap_size
15830 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d ]) and the maxim
15840 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 um allowed mmap
15850 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e size limit..** ^
15860 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 The default sett
15870 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 ing can be overr
15880 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 idden by each da
15890 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
158a0 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 n using.** eithe
158b0 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d r the [PRAGMA mm
158c0 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 ap_size] command
158d0 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 , or by using th
158e0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e e.** [SQLITE_FCN
158f0 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 TL_MMAP_SIZE] fi
15900 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 le control. ^(T
15910 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 he maximum allow
15920 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 ed mmap size.**
15930 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 will be silently
15940 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 truncated if ne
15950 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 cessary so that
15960 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 it does not exce
15970 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c ed the.** compil
15980 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d e-time maximum m
15990 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 map size set by
159a0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d the.** [SQLITE_M
159b0 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f AX_MMAP_SIZE] co
159c0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
159d0 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 n.)^.** ^If eith
159e0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 er argument to t
159f0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 his option is ne
15a00 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 gative, then tha
15a10 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a t argument is.**
15a20 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 changed to its
15a30 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 compile-time def
15a40 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 ault..**.** [[SQ
15a50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 LITE_CONFIG_WIN3
15a60 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 2_HEAPSIZE]].**
15a70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
15a80 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 G_WIN32_HEAPSIZE
15a90 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c .** <dd>^The SQL
15aa0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 ITE_CONFIG_WIN32
15ab0 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e _HEAPSIZE option
15ac0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 is only availab
15ad0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a le if SQLite is.
15ae0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 ** compiled for
15af0 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 Windows with the
15b00 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d [SQLITE_WIN32_M
15b10 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 ALLOC] pre-proce
15b20 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 ssor macro.** de
15b30 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 fined. ^SQLITE_C
15b40 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 ONFIG_WIN32_HEAP
15b50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d SIZE takes a 32-
15b60 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 bit unsigned int
15b70 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 eger value.** th
15b80 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 at specifies the
15b90 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 maximum size of
15ba0 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 the created hea
15bb0 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 p..**.** [[SQLIT
15bc0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f E_CONFIG_PCACHE_
15bd0 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 HDRSZ]].** <dt>S
15be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
15bf0 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 CHE_HDRSZ.** <dd
15c00 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e >^The SQLITE_CON
15c10 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a FIG_PCACHE_HDRSZ
15c20 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
15c30 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 single parameter
15c40 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 which.** is a p
15c50 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
15c60 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 eger and writes
15c70 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 into that intege
15c80 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 r the number of
15c90 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 extra.** bytes p
15ca0 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 er page required
15cb0 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 for each page i
15cc0 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 n [SQLITE_CONFIG
15cd0 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 _PAGECACHE]..**
15ce0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 The amount of ex
15cf0 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 tra space requir
15d00 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 ed can change de
15d10 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 pending on the c
15d20 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 ompiler,.** targ
15d30 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 et platform, and
15d40 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e SQLite version.
15d50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
15d60 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a CONFIG_PMASZ]].*
15d70 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
15d80 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 FIG_PMASZ.** <dd
15d90 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e >^The SQLITE_CON
15da0 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e FIG_PMASZ option
15db0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
15dc0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a parameter which.
15dd0 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 ** is an unsigne
15de0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 d integer and se
15df0 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 ts the "Minimum
15e00 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 PMA Size" for th
15e10 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a e multithreaded.
15e20 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 ** sorter to tha
15e30 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 t integer. The
15e40 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 default minimum
15e50 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 PMA Size is set
15e60 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 by the.** [SQLIT
15e70 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 E_SORTER_PMASZ]
15e80 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
15e90 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 ion. New thread
15ea0 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a s are launched.*
15eb0 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 * to help with s
15ec0 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 ort operations w
15ed0 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 hen multithreade
15ee0 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 d sorting.** is
15ef0 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 enabled (using t
15f00 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 he [PRAGMA threa
15f10 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 ds] command) and
15f20 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 the amount of c
15f30 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 ontent.** to be
15f40 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 sorted exceeds t
15f50 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d he page size tim
15f60 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f es the minimum o
15f70 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 f the.** [PRAGMA
15f80 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 cache_size] set
15f90 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 ting and this va
15fa0 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f lue..** </dl>.*/
15fb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
15fc0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
15fd0 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a EAD 1 /* nil *
15fe0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
15ff0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
16000 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 EAD 2 /* nil
16010 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16020 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
16030 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c ZED 3 /* nil
16040 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16050 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
16060 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 4 /* sq
16070 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
16080 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
16090 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
160a0 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 ALLOC 5 /*
160b0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
160c0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
160d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
160e0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f RATCH 6 /
160f0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c * void*, int sz,
16100 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e int N */.#defin
16110 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16120 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 PAGECACHE 7
16130 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 /* void*, int s
16140 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 z, int N */.#def
16150 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
16160 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 G_HEAP
16170 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 8 /* void*, int
16180 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 nByte, int min
16190 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
161a0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
161b0 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f US 9 /* boo
161c0 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 lean */.#define
161d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
161e0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f TEX 10 /
161f0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
16200 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
16210 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
16220 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 G_GETMUTEX 1
16230 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 1 /* sqlite3_mu
16240 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a tex_methods* */.
16250 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 /* previously SQ
16260 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e LITE_CONFIG_CHUN
16270 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 KALLOC 12 which
16280 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a is now unused. *
16290 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 / .#define SQLIT
162a0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
162b0 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 DE 13 /* int
162c0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
162d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
162e0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f ACHE 14 /
162f0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 * no-op */.#defi
16300 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16310 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 _GETPCACHE 15
16320 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 /* no-op */.#d
16330 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
16340 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 FIG_LOG
16350 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 16 /* xFunc, v
16360 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 oid* */.#define
16370 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
16380 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f I 17 /
16390 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 * int */.#define
163a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
163b0 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 CACHE2 18
163c0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 /* sqlite3_pcach
163d0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 e_methods2* */.#
163e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
163f0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 NFIG_GETPCACHE2
16400 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 19 /* sqlite3
16410 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 _pcache_methods2
16420 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
16430 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
16440 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 ING_INDEX_SCAN 2
16450 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 0 /* int */.#de
16460 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16470 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 IG_SQLLOG
16480 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 21 /* xSqllog,
16490 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 void* */.#define
164a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
164b0 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 MAP_SIZE 22
164c0 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 /* sqlite3_int64
164d0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
164e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
164f0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 E_CONFIG_WIN32_H
16500 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 EAPSIZE 23
16510 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f /* int nByte */
16520 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16530 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 CONFIG_PCACHE_HD
16540 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f RSZ 24 /
16550 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 * int *psz */.#d
16560 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
16570 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 FIG_PMASZ
16580 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 25 /* u
16590 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d nsigned int szPm
165a0 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 a */../*.** CAPI
165b0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
165c0 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 onnection Config
165d0 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a uration Options.
165e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
165f0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
16600 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
16610 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
16620 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
16630 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
16640 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
16650 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 nt to the [sqlit
16660 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
16670 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
16680 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 New configurati
16690 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 on options may b
166a0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
166b0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
166c0 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e Lite..** Existin
166d0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 g configuration
166e0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 options might be
166f0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 discontinued.
16700 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 Applications.**
16710 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 should check the
16720 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f return code fro
16730 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f m [sqlite3_db_co
16740 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 nfig()] to make
16750 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 sure that.** the
16760 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e call worked. ^
16770 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f The [sqlite3_db_
16780 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
16790 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
167a0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
167b0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
167c0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
167d0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
167e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
167f0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
16800 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
16810 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
16820 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e G_LOOKASIDE</dt>
16830 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
16840 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 ption takes thre
16850 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 e additional arg
16860 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 uments that dete
16870 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c rmine the .** [l
16880 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
16890 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 allocator] confi
168a0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 guration for the
168b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
168c0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 ction]..** ^The
168d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 first argument (
168e0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
168f0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
16900 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 db_config()] is
16910 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 a.** pointer to
16920 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 a memory buffer
16930 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 to use for looka
16940 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 side memory..**
16950 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
16960 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 ent after the SQ
16970 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
16980 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 OKASIDE verb.**
16990 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 may be NULL in w
169a0 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 hich case SQLite
169b0 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 will allocate t
169c0 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 he.** lookaside
169d0 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 buffer itself us
169e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c ing [sqlite3_mal
169f0 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 loc()]. ^The sec
16a00 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
16a10 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
16a20 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 ach lookaside bu
16a30 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 ffer slot. ^The
16a40 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
16a50 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
16a60 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 .** slots. The
16a70 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 size of the buff
16a80 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 er in the first
16a90 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 argument must be
16aa0 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a greater than.**
16ab0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 or equal to the
16ac0 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 product of the
16ad0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 second and third
16ae0 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 arguments. The
16af0 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 buffer.** must
16b00 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e be aligned to an
16b10 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 8-byte boundary
16b20 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e . ^If the secon
16b30 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
16b40 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
16b50 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f _LOOKASIDE is no
16b60 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 t a multiple of
16b70 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 8, it is interna
16b80 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 lly.** rounded d
16b90 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 own to the next
16ba0 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 smaller multiple
16bb0 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f of 8. ^(The lo
16bc0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a okaside memory.*
16bd0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
16be0 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 for a database c
16bf0 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e onnection can on
16c00 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 ly be changed wh
16c10 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 en that.** conne
16c20 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 ction is not cur
16c30 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f rently using loo
16c40 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f kaside memory, o
16c50 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 r in other words
16c60 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 .** when the "cu
16c70 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 rrent value" ret
16c80 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
16c90 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 ite3_db_status](
16ca0 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 D,[SQLITE_CONFIG
16cb0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 _LOOKASIDE],...)
16cc0 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 is zero..** Any
16cd0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e attempt to chan
16ce0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 ge the lookaside
16cf0 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 memory configur
16d00 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 ation when looka
16d10 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 side.** memory i
16d20 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 s in use leaves
16d30 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f the configuratio
16d40 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 n unchanged and
16d50 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c returns .** [SQL
16d60 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 ITE_BUSY].)^</dd
16d70 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
16d80 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
16d90 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 LE_FKEY</dt>.**
16da0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
16db0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 n is used to ena
16dc0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 ble or disable t
16dd0 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f he enforcement o
16de0 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 f.** [foreign ke
16df0 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 y constraints].
16e00 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 There should be
16e10 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 two additional
16e20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 arguments..** Th
16e30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
16e40 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 is an integer w
16e50 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 hich is 0 to dis
16e60 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d able FK enforcem
16e70 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 ent,.** positive
16e80 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e to enable FK en
16e90 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 forcement or neg
16ea0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 ative to leave F
16eb0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a K enforcement.**
16ec0 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 unchanged. The
16ed0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
16ee0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 r is a pointer t
16ef0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 o an integer int
16f00 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 o which.** is wr
16f10 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 itten 0 or 1 to
16f20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 indicate whether
16f30 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 FK enforcement
16f40 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 is off or on.**
16f50 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 following this c
16f60 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 all. The second
16f70 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
16f80 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 e a NULL pointer
16f90 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 , in.** which ca
16fa0 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 se the FK enforc
16fb0 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 ement setting is
16fc0 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 not reported ba
16fd0 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ck. </dd>.**.**
16fe0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
16ff0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 FIG_ENABLE_TRIGG
17000 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 ER</dt>.** <dd>
17010 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 ^This option is
17020 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f used to enable o
17030 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 r disable [CREAT
17040 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 E TRIGGER | trig
17050 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 gers]..** There
17060 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 should be two ad
17070 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e ditional argumen
17080 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ts..** The first
17090 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 argument is an
170a0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 integer which is
170b0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 0 to disable tr
170c0 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 iggers,.** posit
170d0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 ive to enable tr
170e0 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 iggers or negati
170f0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 ve to leave the
17100 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 setting unchange
17110 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 d..** The second
17120 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
17130 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
17140 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 teger into which
17150 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 .** is written 0
17160 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 or 1 to indicat
17170 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 e whether trigge
17180 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 rs are disabled
17190 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f or enabled.** fo
171a0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c llowing this cal
171b0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 l. The second p
171c0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 arameter may be
171d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
171e0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 in.** which case
171f0 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 the trigger set
17200 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f ting is not repo
17210 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e rted back. </dd>
17220 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a .**.** </dl>.*/.
17230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
17240 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
17250 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a E 1001 /*
17260 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a void* int int *
17270 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17280 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
17290 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 _FKEY 1002
172a0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 /* int int* */.#
172b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
172c0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 CONFIG_ENABLE_TR
172d0 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 IGGER 1003 /*
172e0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a int int* */.../*
172f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e .** CAPI3REF: En
17300 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
17310 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 Extended Result
17320 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a Codes.** METHOD:
17330 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
17340 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 The sqlite3_exte
17350 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
17360 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 s() routine enab
17370 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
17380 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 the.** [extended
17390 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 result codes] f
173a0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 eature of SQLite
173b0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 . ^The extended
173c0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 result.** codes
173d0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 are disabled by
173e0 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 default for hist
173f0 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 orical compatibi
17400 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c lity..*/.int sql
17410 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
17420 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 sult_codes(sqlit
17430 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b e3*, int onoff);
17440 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
17450 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f : Last Insert Ro
17460 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 wid.** METHOD: s
17470 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 qlite3.**.** ^Ea
17480 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 ch entry in most
17490 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 SQLite tables (
174a0 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 except for [WITH
174b0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 OUT ROWID] table
174c0 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 s).** has a uniq
174d0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 ue 64-bit signed
174e0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 .** integer key
174f0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 called the [ROWI
17500 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 D | "rowid"]. ^T
17510 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 he rowid is alwa
17520 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 ys available.**
17530 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 as an undeclared
17540 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f column named RO
17550 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f WID, OID, or _RO
17560 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 WID_ as long as
17570 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 those.** names a
17580 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 re not also used
17590 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 by explicitly d
175a0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e eclared columns.
175b0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c ^If.** the tabl
175c0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f e has a column o
175d0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 f type [INTEGER
175e0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 PRIMARY KEY] the
175f0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a n that column.**
17600 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 is another alia
17610 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e s for the rowid.
17620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
17630 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
17640 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 rowid(D) interfa
17650 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b ce returns the [
17660 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a rowid] of the .*
17670 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 * most recent su
17680 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
17690 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 ] into a rowid t
176a0 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c able or [virtual
176b0 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 table].** on da
176c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
176d0 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 n D..** ^Inserts
176e0 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 into [WITHOUT R
176f0 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 OWID] tables are
17700 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a not recorded..*
17710 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 * ^If no success
17720 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e ful [INSERT]s in
17730 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a to rowid tables.
17740 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 ** have ever occ
17750 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 urred on the dat
17760 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
17770 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c D, .** then sql
17780 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
17790 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e _rowid(D) return
177a0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 s zero..**.** ^(
177b0 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f If an [INSERT] o
177c0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 ccurs within a t
177d0 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e rigger or within
177e0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c a [virtual tabl
177f0 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 e].** method, th
17800 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 en this routine
17810 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 will return the
17820 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 [rowid] of the i
17830 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 nserted.** row a
17840 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 s long as the tr
17850 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c igger or virtual
17860 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 table method is
17870 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 running..** But
17880 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 once the trigge
17890 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 r or virtual tab
178a0 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 le method ends,
178b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
178c0 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 ed .** by this r
178d0 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 outine reverts t
178e0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 o what it was be
178f0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 fore the trigger
17900 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 or virtual.** t
17910 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 able method bega
17920 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b n.)^.**.** ^An [
17930 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 INSERT] that fai
17940 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 ls due to a cons
17950 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e traint violation
17960 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 is not a.** suc
17970 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
17980 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 and does not ch
17990 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 ange the value r
179a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a eturned by this.
179b0 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 ** routine. ^Th
179c0 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 us INSERT OR FAI
179d0 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e L, INSERT OR IGN
179e0 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 ORE, INSERT OR R
179f0 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 OLLBACK,.** and
17a00 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 INSERT OR ABORT
17a10 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 make no changes
17a20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 to the return va
17a30 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 lue of this.** r
17a40 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 outine when thei
17a50 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c r insertion fail
17a60 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 s. ^(When INSER
17a70 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 T OR REPLACE.**
17a80 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e encounters a con
17a90 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f straint violatio
17aa0 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 n, it does not f
17ab0 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 ail. The.** INS
17ac0 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f ERT continues to
17ad0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 completion afte
17ae0 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 r deleting rows
17af0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 that caused.** t
17b00 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 he constraint pr
17b10 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 oblem so INSERT
17b20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 OR REPLACE will
17b30 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a always change.**
17b40 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
17b50 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 e of this interf
17b60 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f ace.)^.**.** ^Fo
17b70 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f r the purposes o
17b80 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 f this routine,
17b90 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 an [INSERT] is c
17ba0 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 onsidered to.**
17bb0 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 be successful ev
17bc0 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 en if it is subs
17bd0 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 equently rolled
17be0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 back..**.** This
17bf0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 function is acc
17c00 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 essible to SQL s
17c10 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 tatements via th
17c20 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 e.** [last_inser
17c30 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 t_rowid() SQL fu
17c40 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 nction]..**.** I
17c50 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
17c60 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e ead performs a n
17c70 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 ew [INSERT] on t
17c80 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 he same.** datab
17c90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 ase connection w
17ca0 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 hile the [sqlite
17cb0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
17cc0 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 wid()].** functi
17cd0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e on is running an
17ce0 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 d thus changes t
17cf0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b he last insert [
17d00 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 rowid],.** then
17d10 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
17d20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c ed by [sqlite3_l
17d30 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
17d40 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 ()] is.** unpred
17d50 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 ictable and migh
17d60 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 t not equal eith
17d70 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 er the old or th
17d80 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e e new.** last in
17d90 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f sert [rowid]..*/
17da0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
17db0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
17dc0 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 rt_rowid(sqlite3
17dd0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
17de0 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e REF: Count The N
17df0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
17e00 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 dified.** METHOD
17e10 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
17e20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 ^This function r
17e30 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
17e40 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 r of rows modifi
17e50 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a ed, inserted or.
17e60 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 ** deleted by th
17e70 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 e most recently
17e80 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 completed INSERT
17e90 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
17ea0 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 TE.** statement
17eb0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 on the database
17ec0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 connection speci
17ed0 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 fied by the only
17ee0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e parameter..** ^
17ef0 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 Executing any ot
17f00 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 her type of SQL
17f10 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e statement does n
17f20 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 ot modify the va
17f30 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lue.** returned
17f40 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e by this function
17f50 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 ..**.** ^Only ch
17f60 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 anges made direc
17f70 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 tly by the INSER
17f80 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c T, UPDATE or DEL
17f90 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 ETE statement ar
17fa0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 e.** considered
17fb0 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e - auxiliary chan
17fc0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 ges caused by [C
17fd0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 REATE TRIGGER |
17fe0 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b triggers], .** [
17ff0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 foreign key acti
18000 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 ons] or [REPLACE
18010 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 ] constraint res
18020 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 olution are not
18030 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 counted..** .**
18040 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 Changes to a vie
18050 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 w that are inter
18060 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 cepted by .** [I
18070 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 NSTEAD OF trigge
18080 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 r | INSTEAD OF t
18090 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 riggers] are not
180a0 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 counted. ^The v
180b0 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 alue .** returne
180c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 d by sqlite3_cha
180d0 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 nges() immediate
180e0 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 ly after an INSE
180f0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a RT, UPDATE or .*
18100 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 * DELETE stateme
18110 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 nt run on a view
18120 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e is always zero.
18130 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 Only changes ma
18140 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 de to real .** t
18150 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 ables are counte
18160 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 d..**.** Things
18170 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 are more complic
18180 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 ated if the sqli
18190 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 te3_changes() fu
181a0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 nction is.** exe
181b0 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 cuted while a tr
181c0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 igger program is
181d0 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d running. This m
181e0 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 ay happen if the
181f0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 .** program uses
18200 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 the [changes()
18210 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f SQL function], o
18220 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 r if some other
18230 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 callback.** func
18240 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c tion invokes sql
18250 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 ite3_changes() d
18260 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 irectly. Essenti
18270 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c ally:.** .** <ul
18280 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 >.** <li> ^(Be
18290 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 fore entering a
182a0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 trigger program
182b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
182c0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 ed by.**
182d0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
182e0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 ) function is sa
182f0 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 ved. After the t
18300 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a rigger program .
18310 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 ** has fi
18320 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 nished, the orig
18330 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 inal value is re
18340 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a stored.)^.** .**
18350 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e <li> ^(Within
18360 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 a trigger progr
18370 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 am each INSERT,
18380 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 UPDATE and DELET
18390 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 E .** sta
183a0 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 tement sets the
183b0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
183c0 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 y sqlite3_change
183d0 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 s() .** u
183e0 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 pon completion a
183f0 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 s normal. Of cou
18400 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 rse, this value
18410 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 will not include
18420 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 .** any
18430 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 changes performe
18440 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 d by sub-trigger
18450 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 s, as the sqlite
18460 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 3_changes() .**
18470 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c value wil
18480 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 l be saved and r
18490 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 estored after ea
184a0 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 ch sub-trigger h
184b0 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 as run.)^.** </u
184c0 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 l>.** .** ^This
184d0 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 means that if th
184e0 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 e changes() SQL
184f0 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d function (or sim
18500 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a ilar) is used.**
18510 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e by the first IN
18520 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 SERT, UPDATE or
18530 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
18540 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 within a trigge
18550 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e r, it .** return
18560 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 s the value as s
18570 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c et when the call
18580 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 ing statement be
18590 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a gan executing..*
185a0 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 * ^If it is used
185b0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f by the second o
185c0 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 r subsequent suc
185d0 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 h statement with
185e0 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a in a trigger .**
185f0 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 program, the va
18600 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 lue returned ref
18610 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 lects the number
18620 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 of rows modifie
18630 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 d by the .** pre
18640 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 vious INSERT, UP
18650 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 DATE or DELETE s
18660 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 tatement within
18670 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 the same trigger
18680 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
18690 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f the [sqlite3_to
186a0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 tal_changes()] i
186b0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a nterface, the.**
186c0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 [count_changes
186d0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 pragma], and the
186e0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 [changes() SQL
186f0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
18700 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
18710 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e hread makes chan
18720 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ges on the same
18730 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18740 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 ion.** while [sq
18750 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d lite3_changes()]
18760 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
18770 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
18780 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 ned.** is unpred
18790 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 ictable and not
187a0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 meaningful..*/.i
187b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 nt sqlite3_chang
187c0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
187d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
187e0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 otal Number Of R
187f0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 ows Modified.**
18800 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
18810 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
18820 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
18830 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 total number of
18840 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 rows inserted,
18850 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 modified or.** d
18860 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 eleted by all [I
18870 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d NSERT], [UPDATE]
18880 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 or [DELETE] sta
18890 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 tements complete
188a0 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 d.** since the d
188b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
188c0 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 on was opened, i
188d0 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 ncluding those e
188e0 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 xecuted as.** pa
188f0 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 rt of trigger pr
18900 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 ograms. ^Executi
18910 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 ng any other typ
18920 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 e of SQL stateme
18930 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 nt.** does not a
18940 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 ffect the value
18950 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
18960 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
18970 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 s()..** .** ^Cha
18980 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 nges made as par
18990 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 t of [foreign ke
189a0 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 y actions] are i
189b0 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a ncluded in the.*
189c0 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f * count, but tho
189d0 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 se made as part
189e0 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 of REPLACE const
189f0 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e raint resolution
18a00 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 are.** not. ^Ch
18a10 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 anges to a view
18a20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 that are interce
18a30 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 pted by INSTEAD
18a40 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 OF triggers .**
18a50 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e are not counted.
18a60 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f .** .** See also
18a70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 the [sqlite3_ch
18a80 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 anges()] interfa
18a90 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e ce, the.** [coun
18aa0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 t_changes pragma
18ab0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 ], and the [tota
18ac0 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 l_changes() SQL
18ad0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
18ae0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
18af0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e hread makes chan
18b00 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ges on the same
18b10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18b20 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 ion.** while [sq
18b30 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
18b40 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e ges()] is runnin
18b50 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 g then the value
18b60 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 .** returned is
18b70 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
18b80 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c d not meaningful
18b90 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
18ba0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 _total_changes(s
18bb0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
18bc0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 CAPI3REF: Inter
18bd0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e rupt A Long-Runn
18be0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 ing Query.** MET
18bf0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
18c00 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
18c10 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e n causes any pen
18c20 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 ding database op
18c30 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 eration to abort
18c40 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 and.** return a
18c50 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f t its earliest o
18c60 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 pportunity. This
18c70 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 routine is typi
18c80 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 cally.** called
18c90 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 in response to a
18ca0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 user action suc
18cb0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 h as pressing "C
18cc0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 ancel".** or Ctr
18cd0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 l-C where the us
18ce0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 er wants a long
18cf0 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 query operation
18d00 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 to halt.** immed
18d10 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 iately..**.** ^I
18d20 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c t is safe to cal
18d30 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 l this routine f
18d40 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 rom a thread dif
18d50 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a ferent from the.
18d60 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 ** thread that i
18d70 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e s currently runn
18d80 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 ing the database
18d90 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 operation. But
18da0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 it.** is not sa
18db0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 fe to call this
18dc0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b routine with a [
18dd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18de0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 ion] that.** is
18df0 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 closed or might
18e00 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c close before sql
18e10 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
18e20 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
18e30 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 ^If an SQL opera
18e40 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 tion is very nea
18e50 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 rly finished at
18e60 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a the time when.**
18e70 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
18e80 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 pt() is called,
18e90 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f then it might no
18ea0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 t have an opport
18eb0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 unity.** to be i
18ec0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d nterrupted and m
18ed0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f ight continue to
18ee0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a completion..**.
18ef0 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 ** ^An SQL opera
18f00 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 tion that is int
18f10 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 errupted will re
18f20 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 turn [SQLITE_INT
18f30 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 ERRUPT]..** ^If
18f40 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 the interrupted
18f50 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 SQL operation is
18f60 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 an INSERT, UPDA
18f70 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a TE, or DELETE.**
18f80 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 that is inside
18f90 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e an explicit tran
18fa0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 saction, then th
18fb0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 e entire transac
18fc0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 tion.** will be
18fd0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f rolled back auto
18fe0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a matically..**.**
18ff0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
19000 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 terrupt(D) call
19010 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 is in effect unt
19020 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 il all currently
19030 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 running.** SQL
19040 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 statements on [d
19050 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19060 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 on] D complete.
19070 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 ^Any new SQL st
19080 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
19090 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
190a0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 er the sqlite3_i
190b0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 nterrupt() call
190c0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a and before the .
190d0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 ** running state
190e0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 ments reaches ze
190f0 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 ro are interrupt
19100 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 ed as if they ha
19110 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e d been.** runnin
19120 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 g prior to the s
19130 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
19140 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 () call. ^New S
19150 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
19160 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 that are starte
19170 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e d after the runn
19180 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f ing statement co
19190 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f unt reaches zero
191a0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 are.** not effe
191b0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 cted by the sqli
191c0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e te3_interrupt().
191d0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 .** ^A call to s
191e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
191f0 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 (D) that occurs
19200 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e when there are n
19210 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c o running.** SQL
19220 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 statements is a
19230 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e no-op and has n
19240 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 o effect on SQL
19250 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
19260 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 at are started a
19270 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 fter the sqlite3
19280 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
19290 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a l returns..**.**
192a0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 If the database
192b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 connection clos
192c0 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 es while [sqlite
192d0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 3_interrupt()].*
192e0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 * is running the
192f0 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c n bad things wil
19300 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e l likely happen.
19310 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
19320 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 _interrupt(sqlit
19330 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
19340 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 I3REF: Determine
19350 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 If An SQL State
19360 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 ment Is Complete
19370 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
19380 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c tines are useful
19390 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d during command-
193a0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 line input to de
193b0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a termine if the.*
193c0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 * currently ente
193d0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 red text seems t
193e0 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 o form a complet
193f0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
19400 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f or.** if additio
19410 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 nal input is nee
19420 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 ded before sendi
19430 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f ng the text into
19440 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 .** SQLite for p
19450 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 arsing. ^These
19460 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
19470 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 1 if the input s
19480 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 tring.** appears
19490 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 to be a complet
194a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e e SQL statement.
194b0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 ^A statement i
194c0 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a s judged to be.*
194d0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 * complete if it
194e0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d ends with a sem
194f0 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 icolon token and
19500 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 is not a prefix
19510 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f of a.** well-fo
19520 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 rmed CREATE TRIG
19530 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 GER statement.
19540 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 ^Semicolons that
19550 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 are embedded wi
19560 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c thin.** string l
19570 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 iterals or quote
19580 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d d identifier nam
19590 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 es or comments a
195a0 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 re not.** indepe
195b0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 ndent tokens (th
195c0 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 ey are part of t
195d0 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 he token in whic
195e0 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d h they are.** em
195f0 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 bedded) and thus
19600 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 do not count as
19610 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 a statement ter
19620 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 minator. ^White
19630 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d space.** and com
19640 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f ments that follo
19650 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 w the final semi
19660 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 colon are ignore
19670 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 d..**.** ^These
19680 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
19690 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 0 if the stateme
196a0 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 nt is incomplete
196b0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f . ^If a.** memo
196c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
196d0 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 ils, then SQLITE
196e0 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e _NOMEM is return
196f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 ed..**.** ^These
19700 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 routines do not
19710 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 parse the SQL s
19720 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a tatements thus.*
19730 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 * will not detec
19740 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 t syntactically
19750 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a incorrect SQL..*
19760 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 *.** ^(If SQLite
19770 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e has not been in
19780 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 itialized using
19790 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
197a0 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a ize()] prior .**
197b0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c to invoking sql
197c0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
197d0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 ) then sqlite3_i
197e0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
197f0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 nvoked.** automa
19800 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 tically by sqlit
19810 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e e3_complete16().
19820 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 If that initia
19830 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a lization fails,.
19840 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 ** then the retu
19850 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 rn value from sq
19860 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
19870 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a () will be non-z
19880 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 ero.** regardles
19890 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
198a0 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 not the input SQ
198b0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e L is complete.)^
198c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 .**.** The input
198d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d to [sqlite3_com
198e0 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 plete()] must be
198f0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
19900 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 ed.** UTF-8 stri
19910 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e ng..**.** The in
19920 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
19930 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 complete16()] mu
19940 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 st be a zero-ter
19950 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 minated.** UTF-1
19960 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 6 string in nati
19970 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
19980 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f /.int sqlite3_co
19990 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 mplete(const cha
199a0 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c r *sql);.int sql
199b0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
199c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 const void *sql)
199d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
199e0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 F: Register A Ca
199f0 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 llback To Handle
19a00 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 SQLITE_BUSY Err
19a10 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ors.** KEYWORDS:
19a20 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 {busy-handler c
19a30 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 allback} {busy h
19a40 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f andler}.** METHO
19a50 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
19a60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 ^The sqlite3_bu
19a70 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 sy_handler(D,X,P
19a80 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 ) routine sets a
19a90 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
19aa0 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 on X.** that mig
19ab0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 ht be invoked wi
19ac0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 th argument P wh
19ad0 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 enever.** an att
19ae0 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 empt is made to
19af0 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73 access a databas
19b00 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 e table associat
19b10 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 ed with.** [data
19b20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
19b30 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 D when another
19b40 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f thread.** or pro
19b50 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62 cess has the tab
19b60 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 le locked..** Th
19b70 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 e sqlite3_busy_h
19b80 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 andler() interfa
19b90 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d ce is used to im
19ba0 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 plement.** [sqli
19bb0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
19bc0 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 ()] and [PRAGMA
19bd0 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a busy_timeout]..*
19be0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 *.** ^If the bus
19bf0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
19c00 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 LL, then [SQLITE
19c10 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 _BUSY].** is ret
19c20 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
19c30 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 y upon encounter
19c40 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e ing the lock. ^
19c50 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c If the busy call
19c60 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e back.** is not N
19c70 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 ULL, then the ca
19c80 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 llback might be
19c90 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f invoked with two
19ca0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a arguments..**.*
19cb0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
19cc0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 ument to the bus
19cd0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 y handler is a c
19ce0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a opy of the void*
19cf0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a pointer which.*
19d00 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 * is the third a
19d10 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
19d20 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
19d30 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 ). ^The second
19d40 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 argument to.** t
19d50 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
19d60 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
19d70 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 number of times
19d80 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 that the busy ha
19d90 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 ndler has.** bee
19da0 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f n invoked previo
19db0 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d usly for the sam
19dc0 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e e locking event.
19dd0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 ^If the.** bus
19de0 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 y callback retur
19df0 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 ns 0, then no ad
19e00 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 ditional attempt
19e10 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a s are made to.**
19e20 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 access the data
19e30 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 base and [SQLITE
19e40 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e _BUSY] is return
19e50 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 ed.** to the app
19e60 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 lication..** ^If
19e70 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
19e80 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
19e90 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 then another att
19ea0 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 empt.** is made
19eb0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 to access the da
19ec0 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 tabase and the c
19ed0 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a ycle repeats..**
19ee0 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 .** The presence
19ef0 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c of a busy handl
19f00 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 er does not guar
19f10 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 antee that it wi
19f20 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a ll be invoked.**
19f30 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c when there is l
19f40 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 ock contention.
19f50 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 ^If SQLite deter
19f60 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b mines that invok
19f70 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 ing the busy.**
19f80 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 handler could re
19f90 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f sult in a deadlo
19fa0 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 ck, it will go a
19fb0 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 head and return
19fc0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a [SQLITE_BUSY].**
19fd0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 to the applicat
19fe0 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 ion instead of i
19ff0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 nvoking the .**
1a000 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a busy handler..**
1a010 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e Consider a scen
1a020 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 ario where one p
1a030 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
1a040 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 g a read lock th
1a050 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 at.** it is tryi
1a060 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f ng to promote to
1a070 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b a reserved lock
1a080 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 and.** a second
1a090 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 process is hold
1a0a0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c ing a reserved l
1a0b0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 ock that it is t
1a0c0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d rying.** to prom
1a0d0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 ote to an exclus
1a0e0 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 ive lock. The f
1a0f0 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e irst process can
1a100 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 not proceed.** b
1a110 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f ecause it is blo
1a120 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f cked by the seco
1a130 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e nd and the secon
1a140 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 d process cannot
1a150 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 .** proceed beca
1a160 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 use it is blocke
1a170 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 d by the first.
1a180 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 If both process
1a190 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 es.** invoke the
1a1a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 busy handlers,
1a1b0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b neither will mak
1a1c0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 e any progress.
1a1d0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 Therefore,.** S
1a1e0 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 QLite returns [S
1a1f0 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 QLITE_BUSY] for
1a200 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 the first proces
1a210 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 s, hoping that t
1a220 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 his.** will indu
1a230 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f ce the first pro
1a240 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 cess to release
1a250 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e its read lock an
1a260 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 d allow.** the s
1a270 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f econd process to
1a280 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 proceed..**.**
1a290 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 ^The default bus
1a2a0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
1a2b0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 LL..**.** ^(Ther
1a2c0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
1a2d0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
1a2e0 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 ler defined for
1a2f0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 each.** [databas
1a300 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
1a310 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 Setting a new bu
1a320 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 sy handler clear
1a330 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 s any.** previou
1a340 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e sly set handler.
1a350 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 )^ ^Note that c
1a360 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
1a370 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a busy_timeout()].
1a380 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 ** or evaluating
1a390 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 [PRAGMA busy_ti
1a3a0 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 meout=N] will ch
1a3b0 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 ange the.** busy
1a3c0 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 handler and thu
1a3d0 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 s clear any prev
1a3e0 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 iously set busy
1a3f0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 handler..**.** T
1a400 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
1a410 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 should not take
1a420 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 any actions whi
1a430 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a ch modify the.**
1a440 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1a450 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
1a460 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c d the busy handl
1a470 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f er. In other wo
1a480 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 rds,.** the busy
1a490 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 handler is not
1a4a0 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 reentrant. Any
1a4b0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 such actions.**
1a4c0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 result in undefi
1a4d0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
1a4e0 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 .** A busy hand
1a4f0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f ler must not clo
1a500 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
1a510 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 connection.** or
1a520 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1a530 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b ment] that invok
1a540 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ed the busy hand
1a550 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ler..*/.int sqli
1a560 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
1a570 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a (sqlite3*, int(*
1a580 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f )(void*,int), vo
1a590 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
1a5a0 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 I3REF: Set A Bus
1a5b0 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 y Timeout.** MET
1a5c0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
1a5d0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
1a5e0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 sets a [sqlite3
1a5f0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 _busy_handler |
1a600 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 busy handler] th
1a610 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 at sleeps.** for
1a620 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f a specified amo
1a630 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e unt of time when
1a640 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b a table is lock
1a650 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 ed. ^The handle
1a660 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 r.** will sleep
1a670 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 multiple times u
1a680 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d ntil at least "m
1a690 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
1a6a0 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 of sleeping.** h
1a6b0 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e ave accumulated.
1a6c0 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 ^After at leas
1a6d0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f t "ms" milliseco
1a6e0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c nds of sleeping,
1a6f0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 .** the handler
1a700 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 returns 0 which
1a710 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f causes [sqlite3_
1a720 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 step()] to retur
1a730 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 n.** [SQLITE_BUS
1a740 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 Y]..**.** ^Calli
1a750 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ng this routine
1a760 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 with an argument
1a770 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 less than or eq
1a780 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 ual to zero.** t
1a790 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 urns off all bus
1a7a0 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a y handlers..**.*
1a7b0 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e * ^(There can on
1a7c0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 ly be a single b
1a7d0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 usy handler for
1a7e0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 a particular.**
1a7f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1a800 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 tion] at any giv
1a810 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 en moment. If a
1a820 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 nother busy hand
1a830 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e ler.** was defin
1a840 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 ed (using [sqli
1a850 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
1a860 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 ()]) prior to ca
1a870 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f lling.** this ro
1a880 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 utine, that othe
1a890 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 r busy handler i
1a8a0 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a s cleared.)^.**.
1a8b0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 ** See also: [P
1a8c0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f RAGMA busy_timeo
1a8d0 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ut].*/.int sqlit
1a8e0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
1a8f0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 sqlite3*, int ms
1a900 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1a910 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 EF: Convenience
1a920 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e Routines For Run
1a930 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 ning Queries.**
1a940 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
1a950 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 **.** This is a
1a960 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
1a970 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 that is preserv
1a980 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
1a990 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a compatibility..
1a9a0 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 ** Use of this i
1a9b0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
1a9c0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a recommended..**.
1a9d0 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 ** Definition: A
1a9e0 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 <b>result table
1a9f0 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 </b> is memory d
1aa00 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 ata structure cr
1aa10 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 eated by the.**
1aa20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
1aa30 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e le()] interface.
1aa40 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 A result table
1aa50 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 records the.**
1aa60 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 complete query r
1aa70 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 esults from one
1aa80 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e or more queries.
1aa90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 .**.** The table
1aaa0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 conceptually ha
1aab0 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f s a number of ro
1aac0 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 ws and columns.
1aad0 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 But.** these nu
1aae0 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 mbers are not pa
1aaf0 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 rt of the result
1ab00 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 table itself.
1ab10 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 These.** numbers
1ab20 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 are obtained se
1ab30 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e parately. Let N
1ab40 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
1ab50 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 f rows.** and M
1ab60 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 be the number of
1ab70 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 columns..**.**
1ab80 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 A result table i
1ab90 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
1aba0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 inters to zero-t
1abb0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
1abc0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 strings..** Ther
1abd0 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c e are (N+1)*M el
1abe0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 ements in the ar
1abf0 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 ray. The first
1ac00 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 M pointers point
1ac10 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d .** to zero-term
1ac20 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 inated strings t
1ac30 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 hat contain the
1ac40 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f names of the co
1ac50 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 lumns..** The re
1ac60 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 maining entries
1ac70 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 all point to que
1ac80 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c ry results. NUL
1ac90 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a L values result.
1aca0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 ** in NULL point
1acb0 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 ers. All other
1acc0 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 values are in th
1acd0 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 eir UTF-8 zero-t
1ace0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 erminated.** str
1acf0 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 ing representati
1ad00 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 on as returned b
1ad10 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
1ad20 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a n_text()]..**.**
1ad30 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
1ad40 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 might consist of
1ad50 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d one or more mem
1ad60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e ory allocations.
1ad70 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
1ad80 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 fe to pass a res
1ad90 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 ult table direct
1ada0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ly to [sqlite3_f
1adb0 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 ree()]..** A res
1adc0 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 ult table should
1add0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
1ade0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
1adf0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a ree_table()]..**
1ae00 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d .** ^(As an exam
1ae10 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ple of the resul
1ae20 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 t table format,
1ae30 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 suppose a query
1ae40 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 result.** is as
1ae50 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
1ae60 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1ae70 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 .** Name
1ae80 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 | Age.**
1ae90 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------
1aea0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a --------------.*
1aeb0 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 * Alice
1aec0 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 | 43.**
1aed0 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 Bob
1aee0 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 | 28.** C
1aef0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a indy | 21.
1af00 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1af10 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
1af20 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d re are two colum
1af30 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 n (M==2) and thr
1af40 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 ee rows (N==3).
1af50 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 Thus the.** res
1af60 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 ult table has 8
1af70 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 entries. Suppos
1af80 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 e the result tab
1af90 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 le is stored.**
1afa0 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 in an array name
1afb0 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 s azResult. The
1afc0 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 n azResult holds
1afd0 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a this content:.*
1afe0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1aff0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 ><pre>.**
1b000 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d azResult[0]
1b010 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 = "Name";.**
1b020 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1b030 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 1;1] = "Age";.**
1b040 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1b050 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 [2] = "Alice
1b060 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1b070 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 esult[3] = "
1b080 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 43";.** a
1b090 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d zResult[4] =
1b0a0 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 "Bob";.**
1b0b0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 azResult[5
1b0c0 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 ] = "28";.**
1b0d0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1b0e0 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a ;6] = "Cindy";.*
1b0f0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1b100 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b t[7] = "21";
1b110 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1b120 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 kquote>)^.**.**
1b130 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 ^The sqlite3_get
1b140 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f _table() functio
1b150 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 n evaluates one
1b160 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 or more.** semic
1b170 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 olon-separated S
1b180 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e QL statements in
1b190 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
1b1a0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 ated UTF-8.** st
1b1b0 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 ring of its 2nd
1b1c0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 parameter and re
1b1d0 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 turns a result t
1b1e0 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 able to the.** p
1b1f0 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 ointer given in
1b200 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 its 3rd paramete
1b210 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 r..**.** After t
1b220 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 he application h
1b230 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
1b240 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
1b250 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1b260 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 le(),.** it must
1b270 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 pass the result
1b280 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 table pointer t
1b290 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 o sqlite3_free_t
1b2a0 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 able() in order
1b2b0 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 to.** release th
1b2c0 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 e memory that wa
1b2d0 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 s malloced. Bec
1b2e0 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 ause of the way
1b2f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1b300 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e malloc()] happen
1b310 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 s within sqlite3
1b320 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 _get_table(), th
1b330 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e e calling.** fun
1b340 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 ction must not t
1b350 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 ry to call [sqli
1b360 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 te3_free()] dire
1b370 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b ctly. Only.** [
1b380 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
1b390 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f le()] is able to
1b3a0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d release the mem
1b3b0 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 ory properly and
1b3c0 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 safely..**.** T
1b3d0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
1b3e0 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 able() interface
1b3f0 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 is implemented
1b400 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f as a wrapper aro
1b410 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f und.** [sqlite3_
1b420 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 exec()]. The sq
1b430 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1b440 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e ) routine does n
1b450 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a ot have access.*
1b460 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 * to any interna
1b470 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 l data structure
1b480 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 s of SQLite. It
1b490 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 uses only the p
1b4a0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 ublic.** interfa
1b4b0 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e ce defined here.
1b4c0 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e As a consequen
1b4d0 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 ce, errors that
1b4e0 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 occur in the.**
1b4f0 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 wrapper layer ou
1b500 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 tside of the int
1b510 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 ernal [sqlite3_e
1b520 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 xec()] call are
1b530 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 not.** reflected
1b540 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 in subsequent c
1b550 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
1b560 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a _errcode()] or.*
1b570 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 * [sqlite3_errms
1b580 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c g()]..*/.int sql
1b590 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a ite3_get_table(.
1b5a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
1b5b0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 /* An op
1b5c0 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 en database */.
1b5d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
1b5e0 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f l, /* SQL to
1b5f0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
1b600 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 . char ***pazRe
1b610 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 sult, /* Resu
1b620 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 lts of the query
1b630 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 */. int *pnRow
1b640 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e , /* N
1b650 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
1b660 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 rows written her
1b670 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f e */. int *pnCo
1b680 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 lumn, /*
1b690 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 Number of result
1b6a0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e columns written
1b6b0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 here */. char
1b6c0 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 **pzErrmsg
1b6d0 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 /* Error msg wr
1b6e0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b itten here */.);
1b6f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 .void sqlite3_fr
1b700 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a ee_table(char **
1b710 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 result);../*.**
1b720 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 CAPI3REF: Format
1b730 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 ted String Print
1b740 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a ing Functions.**
1b750 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
1b760 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b es are work-alik
1b770 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 es of the "print
1b780 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 f()" family of f
1b790 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d unctions.** from
1b7a0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
1b7b0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 library..** Thes
1b7c0 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 e routines under
1b7d0 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 stand most of th
1b7e0 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 e common K&R for
1b7f0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c matting options,
1b800 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 .** plus some ad
1b810 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 ditional non-sta
1b820 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 ndard formats, d
1b830 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a etailed below..*
1b840 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 * Note that some
1b850 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 of the more obs
1b860 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 cure formatting
1b870 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 options from rec
1b880 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 ent.** C-library
1b890 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f standards are o
1b8a0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 mitted from this
1b8b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
1b8c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1b8d0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e te3_mprintf() an
1b8e0 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e d sqlite3_vmprin
1b8f0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 tf() routines wr
1b900 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 ite their.** res
1b910 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 ults into memory
1b920 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
1b930 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1b940 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 ]..** The string
1b950 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
1b960 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 ese two routines
1b970 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 should be.** re
1b980 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 leased by [sqlit
1b990 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f e3_free()]. ^Bo
1b9a0 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 th routines retu
1b9b0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 rn a.** NULL poi
1b9c0 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 nter if [sqlite3
1b9d0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e _malloc()] is un
1b9e0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
1b9f0 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 enough.** memor
1ba00 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 y to hold the re
1ba10 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a sulting string..
1ba20 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 **.** ^(The sqli
1ba30 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 te3_snprintf() r
1ba40 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 outine is simila
1ba50 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 r to "snprintf()
1ba60 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 " from.** the st
1ba70 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
1ba80 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 . The result is
1ba90 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
1baa0 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 e.** buffer supp
1bab0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f lied as the seco
1bac0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f nd parameter who
1bad0 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e se size is given
1bae0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 by.** the first
1baf0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 parameter. Note
1bb00 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 that the order
1bb10 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 of the.** first
1bb20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 two parameters i
1bb30 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 s reversed from
1bb40 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 snprintf().)^ T
1bb50 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 his is an.** his
1bb60 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 torical accident
1bb70 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 that cannot be
1bb80 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 fixed without br
1bb90 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 eaking.** backwa
1bba0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
1bbb0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 y. ^(Note also
1bbc0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 that sqlite3_snp
1bbd0 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 rintf().** retur
1bbe0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
1bbf0 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 its buffer inste
1bc00 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 ad of the number
1bc10 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 of.** character
1bc20 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 s actually writt
1bc30 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 en into the buff
1bc40 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 er.)^ We admit
1bc50 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 that.** the numb
1bc60 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
1bc70 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 written would b
1bc80 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 e a more useful
1bc90 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 return.** value
1bca0 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 but we cannot ch
1bcb0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 ange the impleme
1bcc0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 ntation of sqlit
1bcd0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
1bce0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 now without bre
1bcf0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c aking compatibil
1bd00 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c ity..**.** ^As l
1bd10 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 ong as the buffe
1bd20 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 r size is greate
1bd30 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c r than zero, sql
1bd40 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
1bd50 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 ** guarantees th
1bd60 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 at the buffer is
1bd70 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 always zero-ter
1bd80 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 minated. ^The f
1bd90 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 irst.** paramete
1bda0 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 r "n" is the tot
1bdb0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 al size of the b
1bdc0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 uffer, including
1bdd0 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 space for.** th
1bde0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
1bdf0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 r. So the longe
1be00 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 st string that c
1be10 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 an be completely
1be20 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c .** written will
1be30 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 be n-1 characte
1be40 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 rs..**.** ^The s
1be50 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 qlite3_vsnprintf
1be60 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 () routine is a
1be70 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 varargs version
1be80 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 of sqlite3_snpri
1be90 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ntf()..**.** The
1bea0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 se routines all
1beb0 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 implement some a
1bec0 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 dditional format
1bed0 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 ting.** options
1bee0 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 that are useful
1bef0 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 for constructing
1bf00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e SQL statements.
1bf10 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 .** All of the u
1bf20 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f sual printf() fo
1bf30 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 rmatting options
1bf40 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 apply. In addi
1bf50 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 tion, there.** i
1bf60 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 s are "%q", "%Q"
1bf70 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 , "%w" and "%z"
1bf80 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e options..**.** ^
1bf90 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 (The %q option w
1bfa0 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 orks like %s in
1bfb0 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 that it substitu
1bfc0 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e tes a nul-termin
1bfd0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 ated.** string f
1bfe0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 rom the argument
1bff0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 list. But %q a
1c000 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 lso doubles ever
1c010 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 y '\'' character
1c020 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 ..** %q is desig
1c030 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 ned for use insi
1c040 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 de a string lite
1c050 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c ral.)^ By doubl
1c060 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a ing each '\''.**
1c070 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 character it es
1c080 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 capes that chara
1c090 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 cter and allows
1c0a0 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 it to be inserte
1c0b0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 d into.** the st
1c0c0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 ring..**.** For
1c0d0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 example, assume
1c0e0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 the string varia
1c0f0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 ble zText contai
1c100 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f ns text as follo
1c110 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
1c120 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1c130 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 char *zText = "I
1c140 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 t's a happy day!
1c150 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c ";.** </pre></bl
1c160 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
1c170 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 One can use this
1c180 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 text in an SQL
1c190 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c statement as fol
1c1a0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
1c1b0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1c1c0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 char *zSQL = s
1c1d0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 qlite3_mprintf("
1c1e0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
1c1f0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c e VALUES('%q')",
1c200 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c zText);.** sql
1c210 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 ite3_exec(db, zS
1c220 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a QL, 0, 0, 0);.**
1c230 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a sqlite3_free(z
1c240 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c SQL);.** </pre><
1c250 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
1c260 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 ** Because the %
1c270 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 q format string
1c280 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 is used, the '\'
1c290 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a ' character in z
1c2a0 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 Text.** is escap
1c2b0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 ed and the SQL g
1c2c0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 enerated is as f
1c2d0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
1c2e0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1c2f0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 ** INSERT INTO
1c300 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 table1 VALUES('I
1c310 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 t''s a happy day
1c320 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 !').** </pre></b
1c330 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1c340 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 This is correct
1c350 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 . Had we used %
1c360 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c s instead of %q,
1c370 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 the generated S
1c380 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 QL.** would have
1c390 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 looked like thi
1c3a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
1c3b0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 uote><pre>.** I
1c3c0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
1c3d0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 1 VALUES('It's a
1c3e0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a happy day!');.*
1c3f0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1c400 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 uote>.**.** This
1c410 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 second example
1c420 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 is an SQL syntax
1c430 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 error. As a ge
1c440 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 neral rule you s
1c450 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 hould.** always
1c460 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f use %q instead o
1c470 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 f %s when insert
1c480 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 ing text into a
1c490 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a string literal..
1c4a0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f **.** ^(The %Q o
1c4b0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
1c4c0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c %q except it al
1c4d0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 so adds single q
1c4e0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 uotes around.**
1c4f0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 the outside of t
1c500 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e he total string.
1c510 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 Additionally,
1c520 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
1c530 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d in the.** argum
1c540 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 ent list is a NU
1c550 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 LL pointer, %Q s
1c560 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 ubstitutes the t
1c570 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 ext "NULL" (with
1c580 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 out.** single qu
1c590 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f otes).)^ So, fo
1c5a0 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 r example, one c
1c5b0 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 ould say:.**.**
1c5c0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1c5d0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c >.** char *zSQL
1c5e0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e = sqlite3_mprin
1c5f0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 tf("INSERT INTO
1c600 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 table VALUES(%Q)
1c610 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 ", zText);.** s
1c620 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 qlite3_exec(db,
1c630 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a zSQL, 0, 0, 0);.
1c640 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ** sqlite3_free
1c650 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 (zSQL);.** </pre
1c660 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1c670 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 *.** The code ab
1c680 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 ove will render
1c690 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 a correct SQL st
1c6a0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a atement in the z
1c6b0 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 SQL.** variable
1c6c0 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 even if the zTex
1c6d0 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 t variable is a
1c6e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
1c6f0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 .** ^(The "%w" f
1c700 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
1c710 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 is like "%q" ex
1c720 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70 cept that it exp
1c730 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f ects to.** be co
1c740 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 ntained within d
1c750 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 ouble-quotes ins
1c760 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 tead of single q
1c770 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a uotes, and it.**
1c780 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 escapes the dou
1c790 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 ble-quote charac
1c7a0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 ter instead of t
1c7b0 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a he single-quote.
1c7c0 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 ** character.)^
1c7d0 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 The "%w" format
1c7e0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 ting option is i
1c7f0 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 ntended for safe
1c800 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 ly inserting.**
1c810 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e table and column
1c820 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f names into a co
1c830 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 nstructed SQL st
1c840 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e atement..**.** ^
1c850 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 (The "%z" format
1c860 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b ting option work
1c870 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 s like "%s" but
1c880 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 with the.** addi
1c890 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 tion that after
1c8a0 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 the string has b
1c8b0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 een read and cop
1c8c0 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 ied into.** the
1c8d0 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 result, [sqlite3
1c8e0 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c _free()] is call
1c8f0 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 ed on the input
1c900 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 string.)^.*/.cha
1c910 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e r *sqlite3_mprin
1c920 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e tf(const char*,.
1c930 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 ..);.char *sqlit
1c940 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 e3_vmprintf(cons
1c950 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 t char*, va_list
1c960 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
1c970 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 _snprintf(int,ch
1c980 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
1c990 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c ...);.char *sql
1c9a0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 ite3_vsnprintf(i
1c9b0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 nt,char*,const c
1c9c0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a har*, va_list);.
1c9d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1c9e0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 Memory Allocati
1c9f0 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a on Subsystem.**.
1ca00 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f ** The SQLite co
1ca10 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 re uses these th
1ca20 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 ree routines for
1ca30 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a all of its own.
1ca40 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f ** internal memo
1ca50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
1ca60 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 eds. "Core" in t
1ca70 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 he previous sent
1ca80 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 ence.** does not
1ca90 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 include operati
1caa0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 ng-system specif
1cab0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 ic VFS implement
1cac0 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 ation. The.** W
1cad0 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 indows VFS uses
1cae0 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 native malloc()
1caf0 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 and free() for s
1cb00 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a ome operations..
1cb10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1cb20 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 e3_malloc() rout
1cb30 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ine returns a po
1cb40 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b inter to a block
1cb50 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 .** of memory at
1cb60 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 least N bytes i
1cb70 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 n length, where
1cb80 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 N is the paramet
1cb90 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 er..** ^If sqlit
1cba0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 e3_malloc() is u
1cbb0 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 nable to obtain
1cbc0 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a sufficient free.
1cbd0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 ** memory, it re
1cbe0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
1cbf0 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 nter. ^If the p
1cc00 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a arameter N to.**
1cc10 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1cc20 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 ) is zero or neg
1cc30 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 ative then sqlit
1cc40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 e3_malloc() retu
1cc50 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f rns.** a NULL po
1cc60 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
1cc70 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 e sqlite3_malloc
1cc80 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 64(N) routine wo
1cc90 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a rks just like.**
1cca0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1ccb0 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e N) except that N
1ccc0 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 is an unsigned
1ccd0 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 64-bit integer i
1cce0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 nstead.** of a s
1ccf0 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 igned 32-bit int
1cd00 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c eger..**.** ^Cal
1cd10 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 ling sqlite3_fre
1cd20 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 e() with a point
1cd30 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 er previously re
1cd40 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c turned.** by sql
1cd50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 ite3_malloc() or
1cd60 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1cd70 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 () releases that
1cd80 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 memory so.** th
1cd90 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 at it might be r
1cda0 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c eused. ^The sql
1cdb0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 ite3_free() rout
1cdc0 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f ine is.** a no-o
1cdd0 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 p if is called w
1cde0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
1cdf0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e er. Passing a N
1ce00 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 ULL pointer.** t
1ce10 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 o sqlite3_free()
1ce20 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 is harmless. A
1ce30 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 fter being freed
1ce40 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 , memory.** shou
1ce50 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 ld neither be re
1ce60 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 ad nor written.
1ce70 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 Even reading pr
1ce80 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a eviously freed.*
1ce90 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 * memory might r
1cea0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 esult in a segme
1ceb0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 ntation fault or
1cec0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
1ced0 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 ror..** Memory c
1cee0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 orruption, a seg
1cef0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c mentation fault,
1cf00 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 or other severe
1cf10 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 error.** might
1cf20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 result if sqlite
1cf30 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 3_free() is call
1cf40 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 ed with a non-NU
1cf50 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a LL pointer that.
1cf60 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 ** was not obtai
1cf70 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
1cf80 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c _malloc() or sql
1cf90 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
1cfa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1cfb0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 e3_realloc(X,N)
1cfc0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
1cfd0 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a ts to resize a.*
1cfe0 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 * prior memory a
1cff0 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 llocation X to b
1d000 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 e at least N byt
1d010 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 es..** ^If the X
1d020 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
1d030 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
1d040 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 N).** is a NULL
1d050 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 pointer then its
1d060 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 behavior is ide
1d070 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e ntical to callin
1d080 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c g.** sqlite3_mal
1d090 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 loc(N)..** ^If t
1d0a0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 he N parameter t
1d0b0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
1d0c0 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f c(X,N) is zero o
1d0d0 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 r.** negative th
1d0e0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
1d0f0 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 is exactly the s
1d100 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a ame as calling.*
1d110 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 * sqlite3_free(X
1d120 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 )..** ^sqlite3_r
1d130 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 ealloc(X,N) retu
1d140 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1d150 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
1d160 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 tion.** of at le
1d170 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 ast N bytes in s
1d180 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 ize or NULL if i
1d190 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f nsufficient memo
1d1a0 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e ry is available.
1d1b0 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 .** ^If M is the
1d1c0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 size of the pri
1d1d0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 or allocation, t
1d1e0 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 hen min(N,M) byt
1d1f0 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 es.** of the pri
1d200 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 or allocation ar
1d210 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 e copied into th
1d220 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 e beginning of b
1d230 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a uffer returned.*
1d240 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 * by sqlite3_rea
1d250 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 lloc(X,N) and th
1d260 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
1d270 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 on is freed..**
1d280 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c ^If sqlite3_real
1d290 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 loc(X,N) returns
1d2a0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 NULL and N is p
1d2b0 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 ositive, then th
1d2c0 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 e.** prior alloc
1d2d0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 ation is not fre
1d2e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
1d2f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 qlite3_realloc64
1d300 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 (X,N) interfaces
1d310 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 works the same
1d320 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 as.** sqlite3_re
1d330 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 alloc(X,N) excep
1d340 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 t that N is a 64
1d350 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e -bit unsigned in
1d360 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a teger instead.**
1d370 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 of a 32-bit sig
1d380 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a ned integer..**.
1d390 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 ** ^If X is a me
1d3a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
1d3b0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
1d3c0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
1d3d0 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 _malloc(),.** sq
1d3e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 lite3_malloc64()
1d3f0 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f , sqlite3_reallo
1d400 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f c(), or sqlite3_
1d410 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 realloc64(), the
1d420 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 n.** sqlite3_msi
1d430 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 ze(X) returns th
1d440 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d e size of that m
1d450 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1d460 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 in bytes..** ^T
1d470 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
1d480 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 d by sqlite3_msi
1d490 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c ze(X) might be l
1d4a0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e arger than the n
1d4b0 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 umber.** of byte
1d4c0 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e s requested when
1d4d0 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 X was allocated
1d4e0 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 . ^If X is a NU
1d4f0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a LL pointer then.
1d500 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 ** sqlite3_msize
1d510 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f (X) returns zero
1d520 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 . If X points t
1d530 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 o something that
1d540 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 is not.** the b
1d550 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f eginning of memo
1d560 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f ry allocation, o
1d570 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 r if it points t
1d580 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 o a formerly.**
1d590 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c valid memory all
1d5a0 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 ocation that has
1d5b0 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c now been freed,
1d5c0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
1d5d0 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 or.** of sqlite3
1d5e0 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 _msize(X) is und
1d5f0 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 efined and possi
1d600 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a bly harmful..**.
1d610 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 ** ^The memory r
1d620 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
1d630 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c e3_malloc(), sql
1d640 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a ite3_realloc(),.
1d650 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
1d660 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 c64(), and sqlit
1d670 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a e3_realloc64().*
1d680 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 * is always alig
1d690 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 ned to at least
1d6a0 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 an 8 byte bounda
1d6b0 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 ry, or to a.** 4
1d6c0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 byte boundary i
1d6d0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f f the [SQLITE_4_
1d6e0 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c BYTE_ALIGNED_MAL
1d6f0 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d LOC] compile-tim
1d700 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 e.** option is u
1d710 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 sed..**.** In SQ
1d720 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
1d730 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 .0 and 3.5.1, it
1d740 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f was possible to
1d750 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 define.** the S
1d760 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 QLITE_OMIT_MEMOR
1d770 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 Y_ALLOCATION whi
1d780 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 ch would cause t
1d790 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 he built-in.** i
1d7a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
1d7b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
1d7c0 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 to be omitted.
1d7d0 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a That capability.
1d7e0 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ** is no longer
1d7f0 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 provided. Only
1d800 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
1d810 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 allocators can b
1d820 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 e used..**.** Pr
1d830 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 ior to SQLite ve
1d840 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 rsion 3.7.10, th
1d850 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 e Windows OS int
1d860 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c erface layer cal
1d870 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 led.** the syste
1d880 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 m malloc() and f
1d890 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 ree() directly w
1d8a0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a hen converting.*
1d8b0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 * filenames betw
1d8c0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e een the UTF-8 en
1d8d0 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 coding used by S
1d8e0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 QLite.** and wha
1d8f0 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 tever filename e
1d900 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 ncoding is used
1d910 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 by the particula
1d920 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 r Windows.** ins
1d930 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f tallation. Memo
1d940 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
1d950 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 rors were detect
1d960 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 ed, but.** they
1d970 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 were reported ba
1d980 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 ck as [SQLITE_CA
1d990 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 NTOPEN] or.** [S
1d9a0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 QLITE_IOERR] rat
1d9b0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
1d9c0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 _NOMEM]..**.** T
1d9d0 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d he pointer argum
1d9e0 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 ents to [sqlite3
1d9f0 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 _free()] and [sq
1da00 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
1da10 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 .** must be eith
1da20 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 er NULL or else
1da30 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 pointers obtaine
1da40 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a d from a prior.*
1da50 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 * invocation of
1da60 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1da70 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
1da80 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 ealloc()] that h
1da90 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 ave.** not yet b
1daa0 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a een released..**
1dab0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
1dac0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 ion must not rea
1dad0 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 d or write any p
1dae0 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 art of.** a bloc
1daf0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 k of memory afte
1db00 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 r it has been re
1db10 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 leased using.**
1db20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1db30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
1db40 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 lloc()]..*/.void
1db50 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 *sqlite3_malloc
1db60 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c (int);.void *sql
1db70 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 ite3_malloc64(sq
1db80 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 lite3_uint64);.v
1db90 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 oid *sqlite3_rea
1dba0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 lloc(void*, int)
1dbb0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f ;.void *sqlite3_
1dbc0 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c realloc64(void*,
1dbd0 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 sqlite3_uint64)
1dbe0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 ;.void sqlite3_f
1dbf0 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 ree(void*);.sqli
1dc00 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 te3_uint64 sqlit
1dc10 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b e3_msize(void*);
1dc20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1dc30 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
1dc40 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a or Statistics.**
1dc50 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 .** SQLite provi
1dc60 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e des these two in
1dc70 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 terfaces for rep
1dc80 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 orting on the st
1dc90 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b atus.** of the [
1dca0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1dcb0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ], [sqlite3_free
1dcc0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
1dcd0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 3_realloc()].**
1dce0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 routines, which
1dcf0 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 form the built-i
1dd00 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
1dd10 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a ion subsystem..*
1dd20 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 *.** ^The [sqlit
1dd30 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
1dd40 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
1dd50 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
1dd60 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f bytes.** of memo
1dd70 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 ry currently out
1dd80 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 standing (malloc
1dd90 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 ed but not freed
1dda0 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 )..** ^The [sqli
1ddb0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
1ddc0 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 ater()] routine
1ddd0 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 returns the maxi
1dde0 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 mum.** value of
1ddf0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
1de00 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 used()] since th
1de10 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 e high-water mar
1de20 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 k.** was last re
1de30 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 set. ^The value
1de40 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
1de50 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
1de60 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 ed()] and.** [sq
1de70 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
1de80 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 hwater()] includ
1de90 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a e any overhead.*
1dea0 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 * added by SQLit
1deb0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 e in its impleme
1dec0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ntation of [sqli
1ded0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a te3_malloc()],.*
1dee0 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 * but not overhe
1def0 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 ad added by the
1df00 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 any underlying s
1df10 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a ystem library.**
1df20 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b routines that [
1df30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1df40 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a ] may call..**.*
1df50 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 * ^The memory hi
1df60 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 gh-water mark is
1df70 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 reset to the cu
1df80 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a rrent value of.*
1df90 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 * [sqlite3_memor
1dfa0 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 y_used()] if and
1dfb0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 only if the par
1dfc0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 ameter to.** [sq
1dfd0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
1dfe0 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 hwater()] is tru
1dff0 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 e. ^The value r
1e000 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 eturned.** by [s
1e010 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
1e020 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 ghwater(1)] is t
1e030 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
1e040 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 rk.** prior to t
1e050 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c he reset..*/.sql
1e060 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
1e070 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 e3_memory_used(v
1e080 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e oid);.sqlite3_in
1e090 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f t64 sqlite3_memo
1e0a0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 ry_highwater(int
1e0b0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a resetFlag);../*
1e0c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 .** CAPI3REF: Ps
1e0d0 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 eudo-Random Numb
1e0e0 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a er Generator.**.
1e0f0 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 ** SQLite contai
1e100 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 ns a high-qualit
1e110 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 y pseudo-random
1e120 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 number generator
1e130 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a (PRNG) used to.
1e140 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d ** select random
1e150 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 [ROWID | ROWIDs
1e160 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 ] when inserting
1e170 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 new records int
1e180 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a o a table that.*
1e190 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 * already uses t
1e1a0 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 he largest possi
1e1b0 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 ble [ROWID]. Th
1e1c0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 e PRNG is also u
1e1d0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 sed for.** the b
1e1e0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 uild-in random()
1e1f0 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 and randomblob(
1e200 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e ) SQL functions.
1e210 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 This interface
1e220 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 allows.** appli
1e230 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 cations to acces
1e240 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 s the same PRNG
1e250 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 for other purpos
1e260 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c es..**.** ^A cal
1e270 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e l to this routin
1e280 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 e stores N bytes
1e290 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 of randomness i
1e2a0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a nto buffer P..**
1e2b0 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 ^The P paramete
1e2c0 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 r can be a NULL
1e2d0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
1e2e0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 If this routine
1e2f0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 has not been pre
1e300 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f viously called o
1e310 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 r if the previou
1e320 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 s.** call had N
1e330 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 less than one or
1e340 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
1e350 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 for P, then the
1e360 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 PRNG is.** seede
1e370 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 d using randomne
1e380 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ss obtained from
1e390 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 the xRandomness
1e3a0 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 method of.** th
1e3b0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
1e3c0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a e3_vfs] object..
1e3d0 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 ** ^If the previ
1e3e0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 ous call to this
1e3f0 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 routine had an
1e400 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 N of 1 or more a
1e410 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c nd a.** non-NULL
1e420 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 P then the pseu
1e430 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 do-randomness is
1e440 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e generated.** in
1e450 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 ternally and wit
1e460 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f hout recourse to
1e470 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
1e480 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a s] xRandomness.*
1e490 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 * method..*/.voi
1e4a0 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d d sqlite3_random
1e4b0 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 ness(int N, void
1e4c0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *P);../*.** CAP
1e4d0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 I3REF: Compile-T
1e4e0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f ime Authorizatio
1e4f0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d n Callbacks.** M
1e500 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
1e510 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
1e520 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 ne registers an
1e530 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1e540 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 ack with a parti
1e550 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 cular.** [databa
1e560 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 se connection],
1e570 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 supplied in the
1e580 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a first argument..
1e590 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a ** ^The authoriz
1e5a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
1e5b0 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 nvoked as SQL st
1e5c0 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 atements are bei
1e5d0 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 ng compiled.** b
1e5e0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 y [sqlite3_prepa
1e5f0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 re()] or its var
1e600 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 iants [sqlite3_p
1e610 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a repare_v2()],.**
1e620 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1e630 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 e16()] and [sqli
1e640 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
1e650 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 ()]. ^At variou
1e660 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 s.** points duri
1e670 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 ng the compilati
1e680 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c on process, as l
1e690 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 ogic is being cr
1e6a0 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 eated.** to perf
1e6b0 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 orm various acti
1e6c0 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 ons, the authori
1e6d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
1e6e0 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 invoked to.** se
1e6f0 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f e if those actio
1e700 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 ns are allowed.
1e710 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 ^The authorizer
1e720 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 callback should
1e730 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
1e740 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 TE_OK] to allow
1e750 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c the action, [SQL
1e760 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 ITE_IGNORE] to d
1e770 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 isallow the.** s
1e780 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 pecific action b
1e790 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c ut allow the SQL
1e7a0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f statement to co
1e7b0 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 ntinue to be.**
1e7c0 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 compiled, or [SQ
1e7d0 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 LITE_DENY] to ca
1e7e0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 use the entire S
1e7f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 QL statement to
1e800 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 be.** rejected w
1e810 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e ith an error. ^
1e820 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 If the authorize
1e830 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 r callback retur
1e840 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 ns.** any value
1e850 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
1e860 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c TE_IGNORE], [SQL
1e870 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c ITE_OK], or [SQL
1e880 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 ITE_DENY].** the
1e890 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 n the [sqlite3_p
1e8a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
1e8b0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 equivalent call
1e8c0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a that triggered.*
1e8d0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
1e8e0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 will fail with
1e8f0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
1e900 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
1e910 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
1e920 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 s [SQLITE_OK], t
1e930 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 hat means the op
1e940 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 eration.** reque
1e950 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 sted is ok. ^Wh
1e960 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
1e970 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
1e980 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 DENY], the.** [s
1e990 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1e9a0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 2()] or equivale
1e9b0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 nt call that tri
1e9c0 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 ggered the.** au
1e9d0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 thorizer will fa
1e9e0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 il with an error
1e9f0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e message explain
1ea00 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 ing that.** acce
1ea10 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a ss is denied. .*
1ea20 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
1ea30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
1ea40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1ea50 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f back is a copy o
1ea60 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 f the third.** p
1ea70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
1ea80 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1ea90 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 orizer() interfa
1eaa0 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 ce. ^The second
1eab0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 parameter.** to
1eac0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
1ead0 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 an integer [SQLI
1eae0 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e TE_COPY | action
1eaf0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 code] that spec
1eb00 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 ifies.** the par
1eb10 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 ticular action t
1eb20 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e o be authorized.
1eb30 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f ^The third thro
1eb40 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 ugh sixth parame
1eb50 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 ters.** to the c
1eb60 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f allback are zero
1eb70 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
1eb80 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e ngs that contain
1eb90 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 additional.** d
1eba0 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 etails about the
1ebb0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
1ebc0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 thorized..**.**
1ebd0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 ^If the action c
1ebe0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 ode is [SQLITE_R
1ebf0 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 EAD].** and the
1ec00 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
1ec10 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
1ec20 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 then the.** [pr
1ec30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1ec40 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 ] statement is c
1ec50 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 onstructed to su
1ec60 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 bstitute.** a NU
1ec70 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 LL value in plac
1ec80 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 e of the table c
1ec90 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 olumn that would
1eca0 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 have.** been re
1ecb0 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b ad if [SQLITE_OK
1ecc0 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 ] had been retur
1ecd0 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 ned. The [SQLIT
1ece0 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 E_IGNORE].** ret
1ecf0 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 urn can be used
1ed00 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 to deny an untru
1ed10 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 sted user access
1ed20 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a to individual.*
1ed30 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 * columns of a t
1ed40 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 able..** ^If the
1ed50 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 action code is
1ed60 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 [SQLITE_DELETE]
1ed70 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
1ed80 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c returns.** [SQL
1ed90 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e ITE_IGNORE] then
1eda0 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 the [DELETE] op
1edb0 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 eration proceeds
1edc0 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 but the.** [tru
1edd0 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 ncate optimizati
1ede0 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 on] is disabled
1edf0 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 and all rows are
1ee00 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 deleted individ
1ee10 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 ually..**.** An
1ee20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 authorizer is us
1ee30 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
1ee40 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
1ee50 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 ring].** SQL sta
1ee60 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 tements from an
1ee70 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
1ee80 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 , to ensure that
1ee90 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
1eea0 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 nts.** do not tr
1eeb0 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 y to access data
1eec0 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c they are not al
1eed0 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 lowed to see, or
1eee0 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f that they do no
1eef0 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 t.** try to exec
1ef00 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 ute malicious st
1ef10 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 atements that da
1ef20 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 mage the databas
1ef30 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 e. For.** examp
1ef40 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
1ef50 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 on may allow a u
1ef60 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 ser to enter arb
1ef70 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 itrary.** SQL qu
1ef80 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 eries for evalua
1ef90 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 tion by a databa
1efa0 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 se. But the app
1efb0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a lication does.**
1efc0 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 not want the us
1efd0 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f er to be able to
1efe0 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 make arbitrary
1eff0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a changes to the.*
1f000 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 * database. An
1f010 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 authorizer could
1f020 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 then be put in
1f030 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a place while the.
1f040 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 ** user-entered
1f050 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 SQL is being [sq
1f060 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
1f070 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a prepared] that.*
1f080 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 * disallows ever
1f090 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 ything except [S
1f0a0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
1f0b0 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 s..**.** Applica
1f0c0 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 tions that need
1f0d0 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 to process SQL f
1f0e0 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f rom untrusted so
1f0f0 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 urces.** might a
1f100 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 lso consider low
1f110 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c ering resource l
1f120 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c imits using [sql
1f130 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
1f140 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 and limiting da
1f150 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e tabase size usin
1f160 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f g the [max_page_
1f170 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a count] [PRAGMA].
1f180 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 ** in addition t
1f190 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f o using an autho
1f1a0 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f rizer..**.** ^(O
1f1b0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 nly a single aut
1f1c0 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 horizer can be i
1f1d0 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 n place on a dat
1f1e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1f1f0 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 .** at a time.
1f200 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c Each call to sql
1f210 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
1f220 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 zer overrides th
1f230 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 e.** previous ca
1f240 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 ll.)^ ^Disable
1f250 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 the authorizer b
1f260 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e y installing a N
1f270 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ULL callback..**
1f280 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 The authorizer
1f290 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 is disabled by d
1f2a0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 efault..**.** Th
1f2b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1f2c0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 lback must not d
1f2d0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
1f2e0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
1f2f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1f300 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
1f310 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a ked the authoriz
1f320 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 er callback..**
1f330 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 Note that [sqlit
1f340 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1f350 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
1f360 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 ep()] both modif
1f370 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 y their.** datab
1f380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
1f390 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 for the meaning
1f3a0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 of "modify" in t
1f3b0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a his paragraph..*
1f3c0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 *.** ^When [sqli
1f3d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1f3e0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 ] is used to pre
1f3f0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 pare a statement
1f400 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 , the.** stateme
1f410 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 nt might be re-p
1f420 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b repared during [
1f430 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1f440 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 due to a .** sch
1f450 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e ema change. Hen
1f460 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 ce, the applicat
1f470 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 ion should ensur
1f480 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f e that the.** co
1f490 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 rrect authorizer
1f4a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e callback remain
1f4b0 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e s in place durin
1f4c0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 g the [sqlite3_s
1f4d0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e tep()]..**.** ^N
1f4e0 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 ote that the aut
1f4f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1f500 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 is invoked only
1f510 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 during.** [sqli
1f520 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
1f530 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 r its variants.
1f540 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 Authorization i
1f550 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d s not.** perform
1f560 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d ed during statem
1f570 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 ent evaluation i
1f580 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 n [sqlite3_step(
1f590 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 )], unless.** as
1f5a0 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 stated in the p
1f5b0 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 revious paragrap
1f5c0 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 h, sqlite3_step(
1f5d0 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c ) invokes.** sql
1f5e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1f5f0 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 ) to reprepare a
1f600 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 statement after
1f610 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 a schema change
1f620 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
1f630 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
1f640 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 . sqlite3*,. i
1f650 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 nt (*xAuth)(void
1f660 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 *,int,const char
1f670 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f *,const char*,co
1f680 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
1f690 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a char*),. void *
1f6a0 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a pUserData.);../*
1f6b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
1f6c0 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 thorizer Return
1f6d0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Codes.**.** The
1f6e0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
1f6f0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 horizer | author
1f700 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 izer callback fu
1f710 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 nction] must.**
1f720 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 return either [S
1f730 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 QLITE_OK] or one
1f740 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f of these two co
1f750 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 nstants in order
1f760 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 .** to signal SQ
1f770 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 Lite whether or
1f780 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 not the action i
1f790 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 s permitted. Se
1f7a0 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 e the.** [sqlite
1f7b0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
1f7c0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f | authorizer do
1f7d0 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 cumentation] for
1f7e0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 additional.** i
1f7f0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
1f800 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 * Note that SQLI
1f810 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 TE_IGNORE is als
1f820 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e o used as a [con
1f830 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e flict resolution
1f840 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e mode].** return
1f850 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c ed from the [sql
1f860 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e ite3_vtab_on_con
1f870 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 flict()] interfa
1f880 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ce..*/.#define S
1f890 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 QLITE_DENY 1
1f8a0 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 /* Abort the SQ
1f8b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 L statement with
1f8c0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 an error */.#de
1f8d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f fine SQLITE_IGNO
1f8e0 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 RE 2 /* Don't
1f8f0 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 allow access, bu
1f900 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 t don't generate
1f910 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a an error */../*
1f920 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
1f930 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 thorizer Action
1f940 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Codes.**.** The
1f950 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
1f960 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 horizer()] inter
1f970 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 face registers a
1f980 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1f990 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e on.** that is in
1f9a0 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 voked to authori
1f9b0 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 ze certain SQL s
1f9c0 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 tatement actions
1f9d0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 . The.** second
1f9e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1f9f0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
1fa00 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 integer code th
1fa10 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 at specifies.**
1fa20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 what action is b
1fa30 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e eing authorized.
1fa40 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 These are the
1fa50 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 integer action c
1fa60 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 odes that.** the
1fa70 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1fa80 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 back may be pass
1fa90 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
1faa0 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 action code valu
1fab0 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 es signify what
1fac0 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f kind of operatio
1fad0 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 n is to be.** au
1fae0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 thorized. The 3
1faf0 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d rd and 4th param
1fb00 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 eters to the aut
1fb10 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 horization.** ca
1fb20 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
1fb30 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 will be paramete
1fb40 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e rs or NULL depen
1fb50 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 ding on which of
1fb60 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 these.** codes
1fb70 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 is used as the s
1fb80 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e econd parameter.
1fb90 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 ^(The 5th para
1fba0 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 meter to the.**
1fbb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1fbc0 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ack is the name
1fbd0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
1fbe0 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c ("main", "temp",
1fbf0 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 .** etc.) if app
1fc00 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 licable.)^ ^The
1fc10 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6th parameter t
1fc20 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 o the authorizer
1fc30 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
1fc40 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
1fc50 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 inner-most trigg
1fc60 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 er or view that
1fc70 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
1fc80 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 or.** the access
1fc90 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c attempt or NULL
1fca0 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 if this access
1fcb0 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 attempt is direc
1fcc0 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d tly from.** top-
1fcd0 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a level SQL code..
1fce0 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */./************
1fcf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1fd00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 ***************
1fd10 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 3rd ************
1fd20 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 4th ***********
1fd30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1fd40 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 _CREATE_INDEX
1fd50 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 1 /* In
1fd60 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
1fd70 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1fd80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1fd90 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 CREATE_TABLE
1fda0 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 2 /* Tab
1fdb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
1fdc0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1fdd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1fde0 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 REATE_TEMP_INDEX
1fdf0 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 3 /* Inde
1fe00 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
1fe10 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
1fe20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
1fe30 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 EATE_TEMP_TABLE
1fe40 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 4 /* Table
1fe50 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1fe60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1fe70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
1fe80 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 ATE_TEMP_TRIGGER
1fe90 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 5 /* Trigge
1fea0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
1feb0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1fec0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
1fed0 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 TE_TEMP_VIEW
1fee0 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6 /* View Na
1fef0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
1ff00 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1ff10 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1ff20 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 E_TRIGGER
1ff30 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 7 /* Trigger
1ff40 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
1ff50 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
1ff60 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1ff70 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 _VIEW
1ff80 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 8 /* View Name
1ff90 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
1ffa0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1ffb0 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 e SQLITE_DELETE
1ffc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 9
1ffd0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1ffe0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1fff0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
20000 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 SQLITE_DROP_IND
20010 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 EX 10
20020 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
20030 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
20040 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
20050 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c SQLITE_DROP_TABL
20060 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 E 11
20070 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
20080 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
20090 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
200a0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
200b0 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 INDEX 12
200c0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
200d0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
200e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
200f0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 LITE_DROP_TEMP_T
20100 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f ABLE 13 /
20110 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
20120 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
20130 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
20140 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 ITE_DROP_TEMP_TR
20150 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a IGGER 14 /*
20160 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
20170 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
20180 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20190 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 TE_DROP_TEMP_VIE
201a0 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 W 15 /*
201b0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
201c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
201d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
201e0 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 E_DROP_TRIGGER
201f0 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 16 /* T
20200 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
20210 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
20220 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
20230 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 _DROP_VIEW
20240 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 17 /* Vi
20250 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
20260 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
20270 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20280 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 INSERT
20290 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 18 /* Tab
202a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
202b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
202c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
202d0 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 RAGMA
202e0 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 19 /* Prag
202f0 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 ma Name 1st
20300 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 arg or NULL */.#
20310 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
20320 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AD
20330 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 /* Table
20340 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d Name Colum
20350 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 n Name */.#d
20360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c efine SQLITE_SEL
20370 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 ECT
20380 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 21 /* NULL
20390 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 NULL
203a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
203b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e fine SQLITE_TRAN
203c0 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 SACTION
203d0 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 22 /* Operati
203e0 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 on NULL
203f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
20400 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 ine SQLITE_UPDAT
20410 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
20420 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 23 /* Table Na
20430 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e me Column N
20440 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
20450 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 ne SQLITE_ATTACH
20460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
20470 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 4 /* Filename
20480 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
20490 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
204a0 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 e SQLITE_DETACH
204b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 25
204c0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e /* Database N
204d0 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 ame NULL
204e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
204f0 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 SQLITE_ALTER_TA
20500 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 BLE 26
20510 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 /* Database Na
20520 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 me Table Name
20530 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
20540 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 SQLITE_REINDEX
20550 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 27
20560 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
20570 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
20580 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
20590 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 QLITE_ANALYZE
205a0 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 28
205b0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
205c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
205d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
205e0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 LITE_CREATE_VTAB
205f0 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f LE 29 /
20600 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
20610 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 Module Name
20620 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
20630 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 ITE_DROP_VTABLE
20640 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 30 /*
20650 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
20660 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 Module Name
20670 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20680 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 TE_FUNCTION
20690 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 31 /*
206a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
206b0 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 Function Name
206c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
206d0 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 E_SAVEPOINT
206e0 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 32 /* O
206f0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 peration S
20700 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a avepoint Name *
20710 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
20720 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 _COPY
20730 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 0 /* No
20740 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a longer used */.
20750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
20760 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 ECURSIVE
20770 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 33 /* NULL
20780 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c NULL
20790 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a */..
207a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
207b0 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 Tracing And Prof
207c0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a iling Functions.
207d0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
207e0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 e3.**.** These r
207f0 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 outines register
20800 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
20810 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 ons that can be
20820 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 used for.** trac
20830 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e ing and profilin
20840 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 g the execution
20850 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 of SQL statement
20860 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 s..**.** ^The ca
20870 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
20880 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 registered by sq
20890 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 lite3_trace() is
208a0 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 invoked at.** v
208b0 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 arious times whe
208c0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
208d0 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 nt is being run
208e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 by [sqlite3_step
208f0 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ()]..** ^The sql
20900 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c ite3_trace() cal
20910 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
20920 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 with a UTF-8 re
20930 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a ndering of the.*
20940 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 * SQL statement
20950 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 text as the stat
20960 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 ement first begi
20970 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a ns executing..**
20980 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 ^(Additional sq
20990 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 lite3_trace() ca
209a0 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 llbacks might oc
209b0 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 cur.** as each t
209c0 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 riggered subprog
209d0 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 ram is entered.
209e0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 The callbacks f
209f0 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 or triggers.** c
20a00 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 ontain a UTF-8 S
20a10 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 QL comment that
20a20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 identifies the t
20a30 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 rigger.)^.**.**
20a40 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 The [SQLITE_TRAC
20a50 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f E_SIZE_LIMIT] co
20a60 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
20a70 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
20a80 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 limit.** the le
20a90 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 ngth of [bound p
20aa0 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 arameter] expans
20ab0 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 ion in the outpu
20ac0 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 t of sqlite3_tra
20ad0 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ce()..**.** ^The
20ae0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
20af0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 on registered by
20b00 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 sqlite3_profile
20b10 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a () is invoked.**
20b20 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 as each SQL sta
20b30 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e tement finishes.
20b40 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 ^The profile c
20b50 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 allback contains
20b60 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c .** the original
20b70 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 statement text
20b80 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 and an estimate
20b90 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 of wall-clock ti
20ba0 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e me.** of how lon
20bb0 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 g that statement
20bc0 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e took to run. ^
20bd0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c The profile call
20be0 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 back.** time is
20bf0 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f in units of nano
20c00 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 seconds, however
20c10 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 the current imp
20c20 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 lementation.** i
20c30 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f s only capable o
20c40 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 f millisecond re
20c50 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 solution so the
20c60 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 six least signif
20c70 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 icant.** digits
20c80 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 in the time are
20c90 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 meaningless. Fu
20ca0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
20cb0 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 SQLite.** might
20cc0 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 provide greater
20cd0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 resolution on t
20ce0 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c he profiler call
20cf0 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 back. The.** sq
20d00 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 lite3_profile()
20d10 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 function is cons
20d20 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e idered experimen
20d30 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 tal and is.** su
20d40 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
20d50 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f in future versio
20d60 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f ns of SQLite..*/
20d70 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 .void *sqlite3_t
20d80 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 race(sqlite3*, v
20d90 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 oid(*xTrace)(voi
20da0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c d*,const char*),
20db0 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f void*);.SQLITE_
20dc0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 EXPERIMENTAL voi
20dd0 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 d *sqlite3_profi
20de0 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 le(sqlite3*,.
20df0 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 void(*xProfile)(
20e00 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 void*,const char
20e10 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 *,sqlite3_uint64
20e20 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ), void*);../*.*
20e30 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 * CAPI3REF: Quer
20e40 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 y Progress Callb
20e50 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 acks.** METHOD:
20e60 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
20e70 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 he sqlite3_progr
20e80 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c ess_handler(D,N,
20e90 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 X,P) interface c
20ea0 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 auses the callba
20eb0 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 ck.** function X
20ec0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 to be invoked p
20ed0 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 eriodically duri
20ee0 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 ng long running
20ef0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c calls to.** [sql
20f00 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 ite3_exec()], [s
20f10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 qlite3_step()] a
20f20 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f nd [sqlite3_get_
20f30 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 table()] for.**
20f40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
20f50 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 ion D. An examp
20f60 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a le use for this.
20f70 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
20f80 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 to keep a GUI up
20f90 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c dated during a l
20fa0 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a arge query..**.*
20fb0 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 * ^The parameter
20fc0 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 P is passed thr
20fd0 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 ough as the only
20fe0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
20ff0 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 e .** callback f
21000 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 unction X. ^The
21010 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 parameter N is
21020 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 the approximate
21030 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 number of .** [v
21040 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 irtual machine i
21050 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 nstructions] tha
21060 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 t are evaluated
21070 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 between successi
21080 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e ve.** invocation
21090 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 s of the callbac
210a0 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c k X. ^If N is l
210b0 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 ess than one the
210c0 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a n the progress.*
210d0 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 * handler is dis
210e0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e abled..**.** ^On
210f0 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 ly a single prog
21100 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 ress handler may
21110 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f be defined at o
21120 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b ne time per.** [
21130 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
21140 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 ion]; setting a
21150 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e new progress han
21160 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 dler cancels the
21170 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 .** old one. ^S
21180 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 etting parameter
21190 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 X to NULL disab
211a0 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 les the progress
211b0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 handler..** ^Th
211c0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
211d0 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 er is also disab
211e0 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e led by setting N
211f0 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 to a value less
21200 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a .** than 1..**.*
21210 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 * ^If the progre
21220 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 ss callback retu
21230 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
21240 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a e operation is.*
21250 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 * interrupted.
21260 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e This feature can
21270 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c be used to impl
21280 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 ement a.** "Canc
21290 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 el" button on a
212a0 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 GUI progress dia
212b0 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 log box..**.** T
212c0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
212d0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 ler callback mus
212e0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
212f0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
21300 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
21310 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
21320 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 at invoked the p
21330 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e rogress handler.
21340 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
21350 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
21360 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
21370 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
21380 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
21390 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
213a0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
213b0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
213c0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
213d0 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 h..**.*/.void sq
213e0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 lite3_progress_h
213f0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
21400 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 int, int(*)(voi
21410 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a d*), void*);../*
21420 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 .** CAPI3REF: Op
21430 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 ening A New Data
21440 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a base Connection.
21450 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 ** CONSTRUCTOR:
21460 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
21470 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 hese routines op
21480 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 en an SQLite dat
21490 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 abase file as sp
214a0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a ecified by the .
214b0 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 ** filename argu
214c0 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e ment. ^The filen
214d0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ame argument is
214e0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
214f0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 TF-8 for.** sqli
21500 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 te3_open() and s
21510 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
21520 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 and as UTF-16 i
21530 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
21540 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 e.** order for s
21550 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e qlite3_open16().
21560 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 ^(A [database c
21570 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
21580 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 e is usually.**
21590 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 returned in *ppD
215a0 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 b, even if an er
215b0 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 ror occurs. The
215c0 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 only exception
215d0 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 is that.** if SQ
215e0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 Lite is unable t
215f0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 o allocate memor
21600 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 y to hold the [s
21610 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a qlite3] object,.
21620 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 ** a NULL will b
21630 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a e written into *
21640 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 ppDb instead of
21650 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
21660 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 [sqlite3].** ob
21670 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 ject.)^ ^(If the
21680 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
21690 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 ned (and/or crea
216a0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c ted) successfull
216b0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 y, then.** [SQLI
216c0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e TE_OK] is return
216d0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 ed. Otherwise a
216e0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
216f0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 s returned.)^ ^T
21700 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 he.** [sqlite3_e
21710 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c rrmsg()] or [sql
21720 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d ite3_errmsg16()]
21730 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 routines can be
21740 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a used to obtain.
21750 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 ** an English la
21760 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 nguage descripti
21770 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 on of the error
21780 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c following a fail
21790 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 ure of any.** of
217a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 the sqlite3_ope
217b0 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a n() routines..**
217c0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 .** ^The default
217d0 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 encoding will b
217e0 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 e UTF-8 for data
217f0 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 bases created us
21800 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f ing.** sqlite3_o
21810 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
21820 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 _open_v2(). ^Th
21830 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 e default encodi
21840 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 ng for databases
21850 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e .** created usin
21860 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 g sqlite3_open16
21870 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 () will be UTF-1
21880 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 6 in the native
21890 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a byte order..**.*
218a0 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * Whether or not
218b0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
218c0 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e when it is open
218d0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a ed, resources.**
218e0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
218f0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
21900 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
21910 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 e should be rele
21920 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 ased by.** passi
21930 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
21940 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 3_close()] when
21950 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 it is no longer
21960 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
21970 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e The sqlite3_open
21980 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 _v2() interface
21990 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
219a0 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 e3_open().** exc
219b0 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 ept that it acce
219c0 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e pts two addition
219d0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f al parameters fo
219e0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e r additional con
219f0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 trol.** over the
21a00 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
21a10 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 nnection. ^(The
21a20 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
21a30 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f to.** sqlite3_o
21a40 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b pen_v2() can tak
21a50 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 e one of.** the
21a60 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 following three
21a70 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c values, optional
21a80 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 ly combined with
21a90 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 the .** [SQLITE
21aa0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 _OPEN_NOMUTEX],
21ab0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c [SQLITE_OPEN_FUL
21ac0 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 LMUTEX], [SQLITE
21ad0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
21ae0 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f E],.** [SQLITE_O
21af0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
21b00 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 ], and/or [SQLIT
21b10 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 E_OPEN_URI] flag
21b20 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a s:)^.**.** <dl>.
21b30 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 ** ^(<dt>[SQLITE
21b40 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c _OPEN_READONLY]<
21b50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
21b60 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
21b70 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 ed in read-only
21b80 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 mode. If the da
21b90 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a tabase does not.
21ba0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ** already exist
21bb0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 , an error is re
21bc0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a turned.</dd>)^.*
21bd0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 *.** ^(<dt>[SQLI
21be0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
21bf0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 E]</dt>.** <dd>T
21c00 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
21c10 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e pened for readin
21c20 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 g and writing if
21c30 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 possible, or re
21c40 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 ading.** only if
21c50 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 the file is wri
21c60 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 te protected by
21c70 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
21c80 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 stem. In either
21c90 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 .** case the dat
21ca0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 abase must alrea
21cb0 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 dy exist, otherw
21cc0 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 ise an error is
21cd0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e returned.</dd>)^
21ce0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 .**.** ^(<dt>[SQ
21cf0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
21d00 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
21d10 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e PEN_CREATE]</dt>
21d20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
21d30 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
21d40 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 or reading and w
21d50 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 riting, and is c
21d60 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 reated if.** it
21d70 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 does not already
21d80 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 exist. This is
21d90 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 the behavior tha
21da0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 t is always used
21db0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
21dc0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
21dd0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 e3_open16().</dd
21de0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a >)^.** </dl>.**.
21df0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 ** If the 3rd pa
21e00 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
21e10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
21e20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a not one of the.*
21e30 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 * combinations s
21e40 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f hown above optio
21e50 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 nally combined w
21e60 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 ith other.** [SQ
21e70 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
21e80 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e LY | SQLITE_OPEN
21e90 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e _* bits].** then
21ea0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
21eb0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
21ec0 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 * ^If the [SQLIT
21ed0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 E_OPEN_NOMUTEX]
21ee0 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 flag is set, the
21ef0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
21f00 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 onnection.** ope
21f10 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d ns in the multi-
21f20 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e thread [threadin
21f30 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 g mode] as long
21f40 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 as the single-th
21f50 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 read.** mode has
21f60 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 not been set at
21f70 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 compile-time or
21f80 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 start-time. ^I
21f90 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 f the.** [SQLITE
21fa0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d _OPEN_FULLMUTEX]
21fb0 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 flag is set the
21fc0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
21fd0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a onnection opens.
21fe0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c ** in the serial
21ff0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 ized [threading
22000 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e mode] unless sin
22010 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a gle-thread was.*
22020 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c * previously sel
22030 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 ected at compile
22040 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 -time or start-t
22050 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ime..** ^The [SQ
22060 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
22070 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 CACHE] flag caus
22080 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
22090 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 connection to be
220a0 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 .** eligible to
220b0 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 use [shared cach
220c0 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c e mode], regardl
220d0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
220e0 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 r not shared.**
220f0 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 cache is enabled
22100 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
22110 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 enable_shared_ca
22120 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a che()]. ^The.**
22130 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 [SQLITE_OPEN_PR
22140 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 IVATECACHE] flag
22150 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 causes the data
22160 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
22170 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 to not.** partic
22180 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 ipate in [shared
22190 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 cache mode] eve
221a0 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c n if it is enabl
221b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ed..**.** ^The f
221c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
221d0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
221e0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 v2() is the name
221f0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
22200 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 te3_vfs] object
22210 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 that defines the
22220 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
22230 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 m interface that
22240 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 .** the new data
22250 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
22260 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 should use. ^If
22270 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
22280 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 meter is.** a NU
22290 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
222a0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
222b0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
222c0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
222d0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ^If the filename
222e0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 is ":memory:",
222f0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 then a private,
22300 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d temporary in-mem
22310 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 ory database.**
22320 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 is created for t
22330 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 he connection.
22340 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 ^This in-memory
22350 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 database will va
22360 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 nish when.** the
22370 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
22380 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 tion is closed.
22390 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 Future versions
223a0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 of SQLite might
223b0 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 .** make use of
223c0 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 additional speci
223d0 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 al filenames tha
223e0 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 t begin with the
223f0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a ":" character..
22400 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 ** It is recomme
22410 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 nded that when a
22420 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 database filena
22430 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 me actually does
22440 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 begin with.** a
22450 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 ":" character y
22460 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 ou should prefix
22470 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 the filename wi
22480 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 th a pathname su
22490 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f ch as.** "./" to
224a0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 avoid ambiguity
224b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
224c0 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 filename is an e
224d0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 mpty string, the
224e0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d n a private, tem
224f0 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 porary.** on-dis
22500 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 k database will
22510 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 be created. ^Th
22520 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 is private datab
22530 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 ase will be.** a
22540 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c utomatically del
22550 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 eted as soon as
22560 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
22570 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
22580 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 d..**.** [[URI f
22590 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 ilenames in sqli
225a0 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 te3_open()]] <h3
225b0 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f >URI Filenames</
225c0 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 h3>.**.** ^If [U
225d0 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 RI filename] int
225e0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 erpretation is e
225f0 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 nabled, and the
22600 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
22610 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 t.** begins with
22620 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 "file:", then t
22630 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 he filename is i
22640 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
22650 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c URI. ^URI.** fil
22660 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 ename interpreta
22670 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 tion is enabled
22680 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f if the [SQLITE_O
22690 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 PEN_URI] flag is
226a0 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 .** set in the f
226b0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 ourth argument t
226c0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
226d0 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 2(), or if it ha
226e0 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 s.** been enable
226f0 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 d globally using
22700 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
22710 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 FIG_URI] option
22720 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c with the.** [sql
22730 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d ite3_config()] m
22740 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 ethod or by the
22750 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d [SQLITE_USE_URI]
22760 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
22770 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 tion..** As of S
22780 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
22790 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 7.7, URI filenam
227a0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e e interpretation
227b0 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a is turned off.*
227c0 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 * by default, bu
227d0 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 t future release
227e0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
227f0 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c t enable URI fil
22800 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 ename.** interpr
22810 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 etation by defau
22820 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 lt. See "[URI f
22830 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 ilenames]" for a
22840 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
22850 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
22860 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 URI filenames ar
22870 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 e parsed accordi
22880 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 ng to RFC 3986.
22890 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 ^If the URI cont
228a0 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f ains an.** autho
228b0 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 rity, then it mu
228c0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 st be either an
228d0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 empty string or
228e0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 the string .** "
228f0 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 localhost". ^If
22900 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 the authority is
22910 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 not an empty st
22920 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f ring or "localho
22930 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f st", an .** erro
22940 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f r is returned to
22950 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 the caller. ^Th
22960 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f e fragment compo
22970 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 nent of a URI, i
22980 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 f .** present, i
22990 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a s ignored..**.**
229a0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 ^SQLite uses th
229b0 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 e path component
229c0 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 of the URI as t
229d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
229e0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 isk file.** whic
229f0 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 h contains the d
22a00 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 atabase. ^If the
22a10 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 path begins wit
22a20 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 h a '/' characte
22a30 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 r, .** then it i
22a40 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
22a50 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 an absolute pat
22a60 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 h. ^If the path
22a70 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a does not begin .
22a80 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d ** with a '/' (m
22a90 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 eaning that the
22aa0 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f authority sectio
22ab0 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f n is omitted fro
22ac0 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 m the URI).** th
22ad0 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 en the path is i
22ae0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
22af0 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a relative path. .
22b00 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c ** ^(On windows,
22b10 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f the first compo
22b20 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c nent of an absol
22b30 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 ute path .** is
22b40 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 a drive specific
22b50 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 ation (e.g. "C:"
22b60 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 ).)^.**.** [[cor
22b70 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 e URI query para
22b80 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 meters]].** The
22b90 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 query component
22ba0 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e of a URI may con
22bb0 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 tain parameters
22bc0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 that are interpr
22bd0 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 eted.** either b
22be0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c y SQLite itself,
22bf0 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 or by a [VFS |
22c00 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 custom VFS imple
22c10 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 mentation]..** S
22c20 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 QLite and its bu
22c30 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 ilt-in [VFSes] i
22c40 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 nterpret the.**
22c50 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 following query
22c60 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a parameters:.**.*
22c70 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e * <ul>.** <li>
22c80 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 <b>vfs</b>: ^Th
22c90 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 e "vfs" paramete
22ca0 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f r may be used to
22cb0 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d specify the nam
22cc0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 e of.** a VF
22cd0 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 S object that pr
22ce0 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 ovides the opera
22cf0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 ting system inte
22d00 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c rface that shoul
22d10 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 d.** be used
22d20 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 to access the d
22d30 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 atabase file on
22d40 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f disk. ^If this o
22d50 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a ption is set to.
22d60 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 ** an empty
22d70 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 string the defau
22d80 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 lt VFS object is
22d90 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 used. ^Specifyi
22da0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a ng an unknown.**
22db0 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 VFS is an e
22dc0 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 rror. ^If sqlite
22dd0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 3_open_v2() is u
22de0 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 sed and the vfs
22df0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 option is.**
22e00 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 present, then t
22e10 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 he VFS specified
22e20 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 by the option t
22e30 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 akes precedence
22e40 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 over.** the
22e50 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
22e60 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
22e70 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
22e80 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a open_v2()..**.**
22e90 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c <li> <b>mode<
22ea0 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 /b>: ^(The mode
22eb0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
22ec0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 set to either "
22ed0 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 ro", "rw",.**
22ee0 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d "rwc", or "mem
22ef0 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 ory". Attempting
22f00 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e to set it to an
22f10 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 y other value is
22f20 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 .** an error
22f30 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 )^. .** ^If
22f40 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 "ro" is specifie
22f50 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 d, then the data
22f60 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
22f70 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a or read-only .**
22f80 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 access, jus
22f90 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c t as if the [SQL
22fa0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
22fb0 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e Y] flag had been
22fc0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 set in the .**
22fd0 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 third argume
22fe0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 nt to sqlite3_op
22ff0 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 en_v2(). ^If the
23000 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 mode option is
23010 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 set to .** "
23020 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 rw", then the da
23030 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
23040 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 for read-write
23050 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 (but not create)
23060 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c .** access,
23070 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 as if SQLITE_OP
23080 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 EN_READWRITE (bu
23090 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 t not SQLITE_OPE
230a0 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a N_CREATE) had .*
230b0 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 * been set.
230c0 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 ^Value "rwc" is
230d0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 equivalent to se
230e0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 tting both .**
230f0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 SQLITE_OPEN_R
23100 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c EADWRITE and SQL
23110 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e ITE_OPEN_CREATE.
23120 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f ^If the mode o
23130 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 ption is.**
23140 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 set to "memory"
23150 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d then a pure [in-
23160 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d memory database]
23170 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 that never read
23180 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 s.** or writ
23190 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 es from disk is
231a0 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 used. ^It is an
231b0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 error to specify
231c0 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 a value for.**
231d0 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 the mode par
231e0 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c ameter that is l
231f0 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 ess restrictive
23200 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 than that specif
23210 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 ied by.** th
23220 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 e flags passed i
23230 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 n the third para
23240 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
23250 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a _open_v2()..**.*
23260 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 * <li> <b>cach
23270 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 e</b>: ^The cach
23280 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 e parameter may
23290 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 be set to either
232a0 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 "shared" or.**
232b0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e "private". ^
232c0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 Setting it to "s
232d0 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 hared" is equiva
232e0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 lent to setting
232f0 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 the.** SQLIT
23300 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
23310 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c HE bit in the fl
23320 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 ags argument pas
23330 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 sed to.** sq
23340 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
23350 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 ^Setting the ca
23360 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f che parameter to
23370 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a "private" is .*
23380 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 * equivalent
23390 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 to setting the
233a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
233b0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a ATECACHE bit..**
233c0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 ^If sqlite3
233d0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 _open_v2() is us
233e0 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 ed and the "cach
233f0 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 e" parameter is
23400 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 present in.**
23410 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 a URI filename
23420 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 , its value over
23430 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 rides any behavi
23440 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 or requested by
23450 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 setting.** S
23460 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
23470 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 TECACHE or SQLIT
23480 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
23490 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 HE flag..**.**
234a0 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e <li> <b>psow</b>
234b0 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 : ^The psow para
234c0 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 meter indicates
234d0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
234e0 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 he.** [power
234f0 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 safe overwrite]
23500 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 property does or
23510 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 does not apply
23520 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 to the.** st
23530 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 orage media on w
23540 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73 hich the databas
23550 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a e file resides..
23560 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e **.** <li> <b>n
23570 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 olock</b>: ^The
23580 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 nolock parameter
23590 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 is a boolean qu
235a0 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ery parameter.**
235b0 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65 which if se
235c0 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 t disables file
235d0 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 locking in rollb
235e0 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 ack journal mode
235f0 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 s. This.**
23600 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 is useful for ac
23610 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 cessing a databa
23620 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 se on a filesyst
23630 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 em that does not
23640 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 .** support
23650 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f locking. Cautio
23660 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 n: Database cor
23670 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 ruption might re
23680 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 sult if two.**
23690 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 or more proce
236a0 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 sses write to th
236b0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
236c0 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 and any one of t
236d0 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 hose.** proc
236e0 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 esses uses noloc
236f0 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e k=1..**.** <li>
23700 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 <b>immutable</b
23710 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c >: ^The immutabl
23720 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 e parameter is a
23730 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a boolean query.*
23740 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 * parameter
23750 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 that indicates t
23760 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 hat the database
23770 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 file is stored
23780 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f on.** read-o
23790 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 nly media. ^Whe
237a0 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 n immutable is s
237b0 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d et, SQLite assum
237c0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 es that the.**
237d0 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 database file
237e0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 cannot be chang
237f0 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 ed, even by a pr
23800 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65 ocess with highe
23810 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 r.** privile
23820 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 ge, and so the d
23830 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
23840 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 d read-only and
23850 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 all locking.**
23860 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 and change de
23870 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 tection is disab
23880 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 led. Caution: S
23890 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 etting the immut
238a0 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 able.** prop
238b0 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 erty on a databa
238c0 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 se file that doe
238d0 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 s in fact change
238e0 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 can result.**
238f0 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 in incorrect
23900 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e query results an
23910 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 d/or [SQLITE_COR
23920 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a RUPT] errors..**
23930 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b See also: [
23940 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d SQLITE_IOCAP_IMM
23950 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 UTABLE]..**
23960 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a .** </ul>.**.*
23970 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e * ^Specifying an
23980 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 unknown paramet
23990 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 er in the query
239a0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 component of a U
239b0 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 RI is not an.**
239c0 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 error. Future v
239d0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
239e0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 e might understa
239f0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 nd additional qu
23a00 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ery.** parameter
23a10 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 s. See "[query
23a20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 parameters with
23a30 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 special meaning
23a40 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a to SQLite]" for.
23a50 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e ** additional in
23a60 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
23a70 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 [[URI filename
23a80 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 examples]] <h3>U
23a90 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d RI filename exam
23aa0 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 ples</h3>.**.**
23ab0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 <table border="1
23ac0 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 " align=center c
23ad0 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a ellpadding=5>.**
23ae0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 <tr><th> URI fi
23af0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 lenames <th> Res
23b00 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ults.** <tr><td>
23b10 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 file:data.db <t
23b20 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
23b30 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 Open the file "d
23b40 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 ata.db" in the c
23b50 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 urrent directory
23b60 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 ..** <tr><td> fi
23b70 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 le:/home/fred/da
23b80 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 ta.db<br>.**
23b90 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f file:///ho
23ba0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 me/fred/data.db
23bb0 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <br> .**
23bc0 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f file://localho
23bd0 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 st/home/fred/dat
23be0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a a.db <br> <td> .
23bf0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e ** Open
23c00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
23c10 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 le "/home/fred/d
23c20 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e ata.db"..** <tr>
23c30 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b <td> file://dark
23c40 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 star/home/fred/d
23c50 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 ata.db <td> .**
23c60 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f An erro
23c70 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 r. "darkstar" is
23c80 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 not a recognize
23c90 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 d authority..**
23ca0 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 <tr><td style="w
23cb0 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 hite-space:nowra
23cc0 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 p"> .**
23cd0 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 file:///C:/Docu
23ce0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 ments%20and%20Se
23cf0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b ttings/fred/Desk
23d00 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 top/data.db.**
23d10 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 <td> Windows
23d20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 only: Open the f
23d30 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e ile "data.db" on
23d40 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 fred's desktop
23d50 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 on drive.**
23d60 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 C:. Note th
23d70 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 at the %20 escap
23d80 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d ing in this exam
23d90 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 ple is not stric
23da0 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 tly .**
23db0 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 necessary - spa
23dc0 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 ce characters ca
23dd0 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 n be used litera
23de0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 lly.**
23df0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 in URI filenames
23e00 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 ..** <tr><td> fi
23e10 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d le:data.db?mode=
23e20 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 ro&cache=private
23e30 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
23e40 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 Open file "da
23e50 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 ta.db" in the cu
23e60 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 rrent directory
23e70 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 for read-only ac
23e80 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 cess..**
23e90 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 Regardless of
23ea0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 whether or not s
23eb0 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 hared-cache mode
23ec0 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a is enabled by.*
23ed0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 * defau
23ee0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 lt, use a privat
23ef0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e e cache..** <tr>
23f00 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f <td> file:/home/
23f10 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 fred/data.db?vfs
23f20 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 =unix-dotfile <t
23f30 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f d>.** O
23f40 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f pen file "/home/
23f50 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 fred/data.db". U
23f60 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 se the special V
23f70 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 FS "unix-dotfile
23f80 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ".** th
23f90 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 at uses dot-file
23fa0 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f s in place of po
23fb0 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 six advisory loc
23fc0 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 king..** <tr><td
23fd0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d > file:data.db?m
23fe0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 ode=readonly <td
23ff0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 > .** A
24000 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e n error. "readon
24010 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c ly" is not a val
24020 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 id option for th
24030 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 e "mode" paramet
24040 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a er..** </table>.
24050 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 **.** ^URI hexad
24060 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 ecimal escape se
24070 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 quences (%HH) ar
24080 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 e supported with
24090 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a in the path and.
240a0 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 ** query compone
240b0 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 nts of a URI. A
240c0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 hexadecimal esca
240d0 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 pe sequence cons
240e0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 ists of a.** per
240f0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 cent sign - "%"
24100 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 - followed by ex
24110 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 actly two hexade
24120 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a cimal digits .**
24130 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f specifying an o
24140 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 ctet value. ^Bef
24150 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 ore the path or
24160 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 query components
24170 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c of a.** URI fil
24180 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 ename are interp
24190 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 reted, they are
241a0 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 encoded using UT
241b0 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 F-8 and all .**
241c0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 hexadecimal esca
241d0 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 pe sequences rep
241e0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c laced by a singl
241f0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e e byte containin
24200 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 g the.** corresp
24210 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 onding octet. If
24220 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 this process ge
24230 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c nerates an inval
24240 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e id UTF-8 encodin
24250 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 g,.** the result
24260 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
24270 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 .**.** <b>Note t
24280 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a o Windows users:
24290 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 </b> The encodi
242a0 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 ng used for the
242b0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
242c0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f t.** of sqlite3_
242d0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
242e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 e3_open_v2() mus
242f0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 t be UTF-8, not
24300 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 whatever.** code
24310 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c page is currentl
24320 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 y defined. File
24330 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 names containing
24340 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a international.*
24350 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 * characters mus
24360 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 t be converted t
24370 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f o UTF-8 prior to
24380 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e passing them in
24390 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 to.** sqlite3_op
243a0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f en() or sqlite3_
243b0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a open_v2()..**.**
243c0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 <b>Note to Wind
243d0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 ows Runtime user
243e0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 s:</b> The temp
243f0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 orary directory
24400 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 must be set.** p
24410 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 rior to calling
24420 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
24430 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
24440 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 2(). Otherwise,
24450 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 various.** feat
24460 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 ures that requir
24470 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d e the use of tem
24480 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 porary files may
24490 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 fail..**.** See
244a0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
244b0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a temp_directory].
244c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f */.int sqlite3_o
244d0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 pen(. const cha
244e0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f r *filename, /
244f0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
24500 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 ame (UTF-8) */.
24510 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 sqlite3 **ppDb
24520 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
24530 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
24540 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 e */.);.int sqli
24550 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f te3_open16(. co
24560 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 nst void *filena
24570 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
24580 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
24590 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 16) */. sqlite3
245a0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
245b0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
245c0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
245d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e int sqlite3_open
245e0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 _v2(. const cha
245f0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f r *filename, /
24600 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
24610 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 ame (UTF-8) */.
24620 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c sqlite3 **ppDb,
24630 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
24640 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
24650 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 e */. int flags
24660 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
24670 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e * Flags */. con
24680 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 st char *zVfs
24690 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
246a0 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 VFS module to us
246b0 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.);../*.** C
246c0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 API3REF: Obtain
246d0 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 Values For URI P
246e0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 arameters.**.**
246f0 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 These are utilit
24700 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 y routines, usef
24710 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d ul to VFS implem
24720 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 entations, that
24730 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 check.** to see
24740 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 if a database fi
24750 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 le was a URI tha
24760 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 t contained a sp
24770 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a ecific query .**
24780 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 parameter, and
24790 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 if so obtains th
247a0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 e value of that
247b0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e query parameter.
247c0 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 .**.** If F is t
247d0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
247e0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 name pointer pas
247f0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 sed into the xOp
24800 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a en() method of .
24810 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 ** a VFS impleme
24820 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 ntation when the
24830 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
24840 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 to xOpen() has
24850 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 one or .** more
24860 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f of the [SQLITE_O
24870 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c PEN_URI] or [SQL
24880 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
24890 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a ] bits set and.*
248a0 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 * P is the name
248b0 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 of the query par
248c0 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 ameter, then.**
248d0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 sqlite3_uri_para
248e0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 meter(F,P) retur
248f0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ns the value of
24900 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 the P.** paramet
24910 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 er if it exists
24920 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 or a NULL pointe
24930 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 r if P does not
24940 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 appear as a .**
24950 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 query parameter
24960 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 on F. If P is a
24970 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
24980 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 of F.** has no
24990 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 explicit value,
249a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 then sqlite3_uri
249b0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 _parameter(F,P)
249c0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 returns.** a poi
249d0 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 nter to an empty
249e0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 string..**.** T
249f0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 he sqlite3_uri_b
24a00 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f oolean(F,P,B) ro
24a10 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 utine assumes th
24a20 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 at P is a boolea
24a30 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 n.** parameter a
24a40 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 nd returns true
24a50 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 (1) or false (0)
24a60 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 according to th
24a70 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e e value.** of P.
24a80 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 The sqlite3_ur
24a90 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 i_boolean(F,P,B)
24aa0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
24ab0 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 true (1) if the
24ac0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 .** value of que
24ad0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 ry parameter P i
24ae0 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 s one of "yes",
24af0 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 "true", or "on"
24b00 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f in any.** case o
24b10 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 r if the value b
24b20 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e egins with a non
24b30 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 -zero number. T
24b40 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 he .** sqlite3_u
24b50 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
24b60 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 ) routines retur
24b70 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 ns false (0) if
24b80 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 the value of.**
24b90 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 query parameter
24ba0 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 P is one of "no"
24bb0 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f , "false", or "o
24bc0 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 ff" in any case
24bd0 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c or.** if the val
24be0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 ue begins with a
24bf0 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 numeric zero.
24c00 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 If P is not a qu
24c10 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ery.** parameter
24c20 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 on F or if the
24c30 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f value of P is do
24c40 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 es not match any
24c50 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 of the.** above
24c60 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 , then sqlite3_u
24c70 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
24c80 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 ) returns (B!=0)
24c90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
24ca0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c te3_uri_int64(F,
24cb0 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e P,D) routine con
24cc0 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 verts the value
24cd0 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 of P into a.** 6
24ce0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 4-bit signed int
24cf0 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 eger and returns
24d00 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f that integer, o
24d10 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f r D if P does no
24d20 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 t.** exist. If
24d30 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 the value of P i
24d40 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 s something othe
24d50 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 r than an intege
24d60 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 r, then.** zero
24d70 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
24d80 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 .** If F is a NU
24d90 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
24da0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 sqlite3_uri_par
24db0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 ameter(F,P) retu
24dc0 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 rns NULL and.**
24dd0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c sqlite3_uri_bool
24de0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 ean(F,P,B) retur
24df0 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e ns B. If F is n
24e00 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ot a NULL pointe
24e10 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 r and.** is not
24e20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 a database file
24e30 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 pathname pointer
24e40 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 that SQLite pas
24e50 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 sed into the xOp
24e60 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 en.** VFS method
24e70 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
24e80 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ior of this rout
24e90 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ine is undefined
24ea0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a and probably.**
24eb0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f undesirable..*/
24ec0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
24ed0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 ite3_uri_paramet
24ee0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a er(const char *z
24ef0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 Filename, const
24f00 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 char *zParam);.i
24f10 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 nt sqlite3_uri_b
24f20 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 oolean(const cha
24f30 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 r *zFile, const
24f40 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e char *zParam, in
24f50 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c t bDefault);.sql
24f60 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
24f70 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e e3_uri_int64(con
24f80 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 st char*, const
24f90 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 char*, sqlite3_i
24fa0 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 nt64);.../*.** C
24fb0 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 API3REF: Error C
24fc0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 odes And Message
24fd0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
24fe0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ite3.**.** ^If t
24ff0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 he most recent s
25000 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c qlite3_* API cal
25010 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 l associated wit
25020 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 h .** [database
25030 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 connection] D fa
25040 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 iled, then the s
25050 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 qlite3_errcode(D
25060 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 ) interface.** r
25070 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 eturns the numer
25080 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d ic [result code]
25090 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 or [extended re
250a0 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 sult code] for t
250b0 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e hat.** API call.
250c0 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 .** If the most
250d0 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 recent API call
250e0 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a was successful,.
250f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 ** then the retu
25100 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 rn value from sq
25110 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 lite3_errcode()
25120 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
25130 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
25140 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 tended_errcode()
25150 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
25160 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 the same except
25170 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 that it always
25180 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 returns the .**
25190 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
251a0 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e code] even when
251b0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
251c0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 codes are.** di
251d0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 sabled..**.** ^T
251e0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 he sqlite3_errms
251f0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f g() and sqlite3_
25200 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 errmsg16() retur
25210 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 n English-langua
25220 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 ge.** text that
25230 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
25240 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 ror, as either U
25250 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 TF-8 or UTF-16 r
25260 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
25270 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 ^(Memory to hold
25280 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
25290 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e ge string is man
252a0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e aged internally.
252b0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
252c0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 ion does not nee
252d0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 d to worry about
252e0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 freeing the res
252f0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c ult..** However,
25300 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e the error strin
25310 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 g might be overw
25320 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f ritten or deallo
25330 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 cated by.** subs
25340 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
25350 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
25360 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 erface functions
25370 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
25380 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 qlite3_errstr()
25390 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
253a0 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 s the English-la
253b0 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 nguage text.** t
253c0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 hat describes th
253d0 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c e [result code],
253e0 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 as UTF-8..** ^(
253f0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 Memory to hold t
25400 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
25410 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 string is manag
25420 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a ed internally.**
25430 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 and must not be
25440 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 freed by the ap
25450 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a plication)^..**.
25460 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 ** When the seri
25470 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
25480 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 g mode] is in us
25490 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 e, it might be t
254a0 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 he.** case that
254b0 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f a second error o
254c0 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 ccurs on a separ
254d0 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 ate thread in be
254e0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d tween.** the tim
254f0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 e of the first e
25500 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c rror and the cal
25510 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 l to these inter
25520 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 faces..** When t
25530 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 hat happens, the
25540 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 second error wi
25550 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 ll be reported s
25560 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e ince these.** in
25570 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 terfaces always
25580 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 report the most
25590 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 recent result.
255a0 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 To avoid.** this
255b0 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 , each thread ca
255c0 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 n obtain exclusi
255d0 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 ve use of the [d
255e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
255f0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f on] D.** by invo
25600 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 king [sqlite3_mu
25610 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 tex_enter]([sqli
25620 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 te3_db_mutex](D)
25630 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 ) before beginni
25640 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 ng.** to use D a
25650 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c nd invoking [sql
25660 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
25670 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 ]([sqlite3_db_mu
25680 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a tex](D)) after.*
25690 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 * all calls to t
256a0 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 he interfaces li
256b0 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f sted here are co
256c0 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 mpleted..**.** I
256d0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 f an interface f
256e0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 ails with SQLITE
256f0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 _MISUSE, that me
25700 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 ans the interfac
25710 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 e.** was invoked
25720 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 incorrectly by
25730 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e the application.
25740 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 In that case,
25750 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 the.** error cod
25760 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 e and message ma
25770 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 y or may not be
25780 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 set..*/.int sqli
25790 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 te3_errcode(sqli
257a0 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 te3 *db);.int sq
257b0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
257c0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a rrcode(sqlite3 *
257d0 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 db);.const char
257e0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 *sqlite3_errmsg(
257f0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 sqlite3*);.const
25800 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 void *sqlite3_e
25810 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a rrmsg16(sqlite3*
25820 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
25830 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e qlite3_errstr(in
25840 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
25850 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 REF: Prepared St
25860 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
25870 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 * KEYWORDS: {pre
25880 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d pared statement}
25890 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
258a0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 ments}.**.** An
258b0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
258c0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
258d0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 ts a single SQL
258e0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a statement that.*
258f0 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 * has been compi
25900 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 led into binary
25910 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 form and is read
25920 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 y to be evaluate
25930 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f d..**.** Think o
25940 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 f each SQL state
25950 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 ment as a separa
25960 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 te computer prog
25970 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 ram. The.** ori
25980 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 ginal SQL text i
25990 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 s source code.
259a0 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 A prepared state
259b0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 ment object .**
259c0 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 is the compiled
259d0 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c object code. Al
259e0 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f l SQL must be co
259f0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a nverted into a.*
25a00 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 * prepared state
25a10 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 ment before it c
25a20 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a an be run..**.**
25a30 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 The life-cycle
25a40 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 of a prepared st
25a50 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 atement object u
25a60 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 sually goes like
25a70 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c this:.**.** <ol
25a80 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 >.** <li> Create
25a90 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
25aa0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 atement object u
25ab0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
25ac0 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 epare_v2()]..**
25ad0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 <li> Bind values
25ae0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d to [parameters]
25af0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 using the sqlit
25b00 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 e3_bind_*().**
25b10 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a interfaces..
25b20 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 ** <li> Run the
25b30 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b SQL by calling [
25b40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
25b50 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 one or more time
25b60 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 s..** <li> Reset
25b70 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
25b80 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 atement using [s
25b90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
25ba0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 then go back.**
25bb0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 to step 2.
25bc0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 Do this zero or
25bd0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
25be0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 <li> Destroy the
25bf0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 object using [s
25c00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
25c10 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a )]..** </ol>.*/.
25c20 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
25c30 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 qlite3_stmt sqli
25c40 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a te3_stmt;../*.**
25c50 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 CAPI3REF: Run-t
25c60 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 ime Limits.** ME
25c70 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
25c80 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 .** ^(This inter
25c90 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 face allows the
25ca0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 size of various
25cb0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 constructs to be
25cc0 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 limited.** on a
25cd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 connection by c
25ce0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e onnection basis.
25cf0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 The first para
25d00 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 meter is the.**
25d10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
25d20 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 tion] whose limi
25d30 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f t is to be set o
25d40 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a r queried. The.
25d50 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
25d60 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 ter is one of th
25d70 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 e [limit categor
25d80 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 ies] that define
25d90 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 a.** class of c
25da0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
25db0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 size limited. T
25dc0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
25dd0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 er is the.** new
25de0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 limit for that
25df0 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a construct.)^.**.
25e00 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c ** ^If the new l
25e10 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 imit is a negati
25e20 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c ve number, the l
25e30 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 imit is unchange
25e40 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 d..** ^(For each
25e50 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 limit category
25e60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e SQLITE_LIMIT_<i>
25e70 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 NAME</i> there i
25e80 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 s a .** [limits
25e90 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 | hard upper bou
25ea0 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f nd].** set at co
25eb0 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 mpile-time by a
25ec0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
25ed0 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b acro called.** [
25ee0 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f limits | SQLITE_
25ef0 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d MAX_<i>NAME</i>]
25f00 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 ..** (The "_LIMI
25f10 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 T_" in the name
25f20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f is changed to "_
25f30 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 MAX_".))^.** ^At
25f40 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 tempts to increa
25f50 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 se a limit above
25f60 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 its hard upper
25f70 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c bound are.** sil
25f80 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 ently truncated
25f90 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 to the hard uppe
25fa0 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e r bound..**.** ^
25fb0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 Regardless of wh
25fc0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
25fd0 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 limit was chang
25fe0 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c ed, the .** [sql
25ff0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e ite3_limit()] in
26000 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
26010 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 the prior value
26020 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a of the limit..**
26030 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 ^Hence, to find
26040 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c the current val
26050 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 ue of a limit wi
26060 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 thout changing i
26070 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 t,.** simply inv
26080 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 oke this interfa
26090 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 ce with the thir
260a0 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 d parameter set
260b0 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e to -1..**.** Run
260c0 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 -time limits are
260d0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
260e0 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e e in application
260f0 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a s that manage.**
26100 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 both their own
26110 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
26120 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 e and also datab
26130 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f ases that are co
26140 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 ntrolled.** by u
26150 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 ntrusted externa
26160 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 l sources. An e
26170 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 xample applicati
26180 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a on might be a.**
26190 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 web browser tha
261a0 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 t has its own da
261b0 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 tabases for stor
261c0 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a ing history and.
261d0 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 ** separate data
261e0 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 bases controlled
261f0 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 by JavaScript a
26200 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e pplications down
26210 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 loaded.** off th
26220 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 e Internet. The
26230 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 internal databa
26240 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e ses can be given
26250 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 the.** large, d
26260 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 efault limits.
26270 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 Databases manage
26280 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f d by external so
26290 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 urces can.** be
262a0 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c given much small
262b0 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e er limits design
262c0 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 ed to prevent a
262d0 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 denial of servic
262e0 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 e.** attack. De
262f0 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 velopers might a
26300 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 lso want to use
26310 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 the [sqlite3_set
26320 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a _authorizer()].*
26330 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 * interface to f
26340 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 urther control u
26350 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 ntrusted SQL. T
26360 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 he size of the d
26370 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 atabase.** creat
26380 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 ed by an untrust
26390 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 ed script can be
263a0 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 contained using
263b0 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 the.** [max_pag
263c0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 e_count] [PRAGMA
263d0 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e ]..**.** New run
263e0 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 -time limit cate
263f0 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 gories may be ad
26400 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
26410 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 leases..*/.int s
26420 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c qlite3_limit(sql
26430 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 ite3*, int id, i
26440 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a nt newVal);../*.
26450 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
26460 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 -Time Limit Cate
26470 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 gories.** KEYWOR
26480 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 DS: {limit categ
26490 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 ory} {*limit cat
264a0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 egories}.**.** T
264b0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 hese constants d
264c0 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 efine various pe
264d0 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 rformance limits
264e0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 .** that can be
264f0 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 lowered at run-t
26500 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ime using [sqlit
26510 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 e3_limit()]..**
26520 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 The synopsis of
26530 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 the meanings of
26540 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 the various limi
26550 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f ts is shown belo
26560 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c w..** Additional
26570 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
26580 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 available at [li
26590 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e mits | Limits in
265a0 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 SQLite]..**.**
265b0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 <dl>.** [[SQLITE
265c0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 _LIMIT_LENGTH]]
265d0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
265e0 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a IT_LENGTH</dt>.*
265f0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
26600 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 m size of any st
26610 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 ring or BLOB or
26620 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 table row, in by
26630 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a tes.<dd>)^.**.**
26640 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
26650 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c SQL_LENGTH]] ^(<
26660 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
26670 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a SQL_LENGTH</dt>.
26680 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
26690 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 um length of an
266a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 SQL statement, i
266b0 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a n bytes.</dd>)^.
266c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
266d0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 IMIT_COLUMN]] ^(
266e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
266f0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 _COLUMN</dt>.**
26700 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
26710 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
26720 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 s in a table def
26730 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 inition or in th
26740 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 e.** result set
26750 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 of a [SELECT] or
26760 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
26770 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
26780 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 n an index.** or
26790 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 in an ORDER BY
267a0 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 or GROUP BY clau
267b0 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a se.</dd>)^.**.**
267c0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
267d0 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c EXPR_DEPTH]] ^(<
267e0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
267f0 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a EXPR_DEPTH</dt>.
26800 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
26810 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 um depth of the
26820 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e parse tree on an
26830 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 y expression.</d
26840 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
26850 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
26860 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 ND_SELECT]] ^(<d
26870 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 t>SQLITE_LIMIT_C
26880 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f OMPOUND_SELECT</
26890 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
268a0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
268b0 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 terms in a comp
268c0 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 ound SELECT stat
268d0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ement.</dd>)^.**
268e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
268f0 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c IT_VDBE_OP]] ^(<
26900 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
26910 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 VDBE_OP</dt>.**
26920 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
26930 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 number of instru
26940 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 ctions in a virt
26950 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 ual machine prog
26960 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 ram.** used to i
26970 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 mplement an SQL
26980 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 statement. This
26990 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 limit is not cu
269a0 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 rrently.** enfor
269b0 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 ced, though that
269c0 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 might be added
269d0 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 in some future r
269e0 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c elease of.** SQL
269f0 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ite.</dd>)^.**.*
26a00 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
26a10 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 _FUNCTION_ARG]]
26a20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
26a30 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c IT_FUNCTION_ARG<
26a40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
26a50 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
26a60 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 f arguments on a
26a70 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 function.</dd>)
26a80 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
26a90 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d _LIMIT_ATTACHED]
26aa0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
26ab0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 IMIT_ATTACHED</d
26ac0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
26ad0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
26ae0 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 [ATTACH | attach
26af0 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e ed databases].)^
26b00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
26b10 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f LITE_LIMIT_LIKE_
26b20 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d PATTERN_LENGTH]]
26b30 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 .** ^(<dt>SQLITE
26b40 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 _LIMIT_LIKE_PATT
26b50 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a ERN_LENGTH</dt>.
26b60 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
26b70 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 um length of the
26b80 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e pattern argumen
26b90 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 t to the [LIKE]
26ba0 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 or.** [GLOB] ope
26bb0 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a rators.</dd>)^.*
26bc0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
26bd0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
26be0 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 BER]].** ^(<dt>S
26bf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
26c00 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e ABLE_NUMBER</dt>
26c10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
26c20 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 mum index number
26c30 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 of any [paramet
26c40 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 er] in an SQL st
26c50 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a atement.)^.**.**
26c60 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
26c70 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 TRIGGER_DEPTH]]
26c80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
26c90 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 IT_TRIGGER_DEPTH
26ca0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
26cb0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f maximum depth o
26cc0 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 f recursion for
26cd0 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e triggers.</dd>)^
26ce0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
26cf0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 LIMIT_WORKER_THR
26d00 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c EADS]] ^(<dt>SQL
26d10 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 ITE_LIMIT_WORKER
26d20 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a _THREADS</dt>.**
26d30 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
26d40 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c number of auxil
26d50 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 iary worker thre
26d60 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c ads that a singl
26d70 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
26d80 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 tatement] may st
26d90 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c art.</dd>)^.** <
26da0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
26db0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e SQLITE_LIMIT_LEN
26dc0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 GTH
26dd0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
26de0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 SQLITE_LIMIT_SQ
26df0 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 L_LENGTH
26e00 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
26e10 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 e SQLITE_LIMIT_C
26e20 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 OLUMN
26e30 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 2.#defi
26e40 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
26e50 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 EXPR_DEPTH
26e60 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 3.#def
26e70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
26e80 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 _COMPOUND_SELECT
26e90 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 4.#de
26ea0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
26eb0 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 T_VDBE_OP
26ec0 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 5.#d
26ed0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
26ee0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 IT_FUNCTION_ARG
26ef0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 6.#
26f00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
26f10 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 MIT_ATTACHED
26f20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 7.
26f30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
26f40 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 IMIT_LIKE_PATTER
26f50 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 N_LENGTH 8
26f60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
26f70 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
26f80 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 UMBER
26f90 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 9.#define SQLITE
26fa0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 _LIMIT_TRIGGER_D
26fb0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 EPTH
26fc0 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 10.#define SQLIT
26fd0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 E_LIMIT_WORKER_T
26fe0 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 HREADS
26ff0 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 11../*.** CAPI3
27000 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 REF: Compiling A
27010 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a n SQL Statement.
27020 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 ** KEYWORDS: {SQ
27030 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 L statement comp
27040 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a iler}.** METHOD:
27050 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 sqlite3.** CONS
27060 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 TRUCTOR: sqlite3
27070 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 _stmt.**.** To e
27080 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 xecute an SQL qu
27090 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 ery, it must fir
270a0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 st be compiled i
270b0 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a nto a byte-code.
270c0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 ** program using
270d0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f one of these ro
270e0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 utines..**.** Th
270f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
27100 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 , "db", is a [da
27110 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
27120 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d n] obtained from
27130 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 a.** prior succ
27140 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
27150 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
27160 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
27170 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 2()] or.** [sqli
27180 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 te3_open16()].
27190 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e The database con
271a0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 nection must not
271b0 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 have been close
271c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 d..**.** The sec
271d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a ond argument, "z
271e0 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 Sql", is the sta
271f0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d tement to be com
27200 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a piled, encoded.*
27210 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d * as either UTF-
27220 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 8 or UTF-16. Th
27230 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
27240 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
27250 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 prepare_v2().**
27260 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 interfaces use U
27270 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 TF-8, and sqlite
27280 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 3_prepare16() an
27290 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
272a0 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 e16_v2().** use
272b0 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 UTF-16..**.** ^I
272c0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 f the nByte argu
272d0 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 ment is negative
272e0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 , then zSql is r
272f0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a ead up to the.**
27300 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d first zero term
27310 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 inator. ^If nByt
27320 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 e is positive, t
27330 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a hen it is the.**
27340 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
27350 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e read from zSql.
27360 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a ^If nByte is z
27370 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 ero, then no pre
27380 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
27390 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e nt is generated.
273a0 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 .** If the calle
273b0 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 r knows that the
273c0 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 supplied string
273d0 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 is nul-terminat
273e0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 ed, then.** ther
273f0 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 e is a small per
27400 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 formance advanta
27410 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e ge to passing an
27420 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 nByte parameter
27430 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 that.** is the
27440 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
27450 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 in the input str
27460 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 ing <i>including
27470 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d </i>.** the nul-
27480 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a terminator..**.*
27490 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 * ^If pzTail is
274a0 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 not NULL then *p
274b0 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f zTail is made to
274c0 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 point to the fi
274d0 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 rst byte.** past
274e0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
274f0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d first SQL statem
27500 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 ent in zSql. Th
27510 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c ese routines onl
27520 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 y.** compile the
27530 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 first statement
27540 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a in zSql, so *pz
27550 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 Tail is left poi
27560 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 nting to.** what
27570 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 remains uncompi
27580 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 led..**.** ^*ppS
27590 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e tmt is left poin
275a0 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c ting to a compil
275b0 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ed [prepared sta
275c0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e tement] that can
275d0 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 be.** executed
275e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 using [sqlite3_s
275f0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 tep()]. ^If the
27600 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 re is an error,
27610 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a *ppStmt is set.*
27620 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 * to NULL. ^If
27630 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 the input text c
27640 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 ontains no SQL (
27650 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 if the input is
27660 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 an empty.** stri
27670 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 ng or a comment)
27680 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 then *ppStmt is
27690 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a set to NULL..**
276a0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f The calling pro
276b0 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e cedure is respon
276c0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 sible for deleti
276d0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a ng the compiled.
276e0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
276f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
27700 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 finalize()] afte
27710 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 r it has finishe
27720 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 d with it..** pp
27730 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 Stmt may not be
27740 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 NULL..**.** ^On
27750 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c success, the sql
27760 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 ite3_prepare() f
27770 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 amily of routine
27780 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 s return [SQLITE
27790 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 _OK];.** otherwi
277a0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 se an [error cod
277b0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a e] is returned..
277c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
277d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 3_prepare_v2() a
277e0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
277f0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 re16_v2() interf
27800 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f aces are.** reco
27810 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 mmended for all
27820 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 new programs. Th
27830 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 e two older inte
27840 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 rfaces are retai
27850 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 ned.** for backw
27860 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
27870 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 ty, but their us
27880 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 e is discouraged
27890 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 ..** ^In the "v2
278a0 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 " interfaces, th
278b0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
278c0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 ment.** that is
278d0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 returned (the [s
278e0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a qlite3_stmt] obj
278f0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 ect) contains a
27900 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f copy of the.** o
27910 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 riginal SQL text
27920 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 . This causes th
27930 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
27940 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a )] interface to.
27950 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 ** behave differ
27960 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 ently in three w
27970 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a ays:.**.** <ol>.
27980 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 ** <li>.** ^If t
27990 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
279a0 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 ma changes, inst
279b0 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 ead of returning
279c0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
279d0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 as it.** always
279e0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 used to do, [sq
279f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
27a00 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
27a10 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 recompile the S
27a20 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 QL.** statement
27a30 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 and try to run i
27a40 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 t again. As many
27a50 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f as [SQLITE_MAX_
27a60 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a SCHEMA_RETRY].**
27a70 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 retries will oc
27a80 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 cur before sqlit
27a90 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 e3_step() gives
27aa0 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 up and returns a
27ab0 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 n error..** </li
27ac0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 >.**.** <li>.**
27ad0 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f ^When an error o
27ae0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f ccurs, [sqlite3_
27af0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 step()] will ret
27b00 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 urn one of the d
27b10 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f etailed.** [erro
27b20 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 r codes] or [ext
27b30 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
27b40 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 s]. ^The legacy
27b50 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 behavior was th
27b60 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 at.** [sqlite3_s
27b70 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c tep()] would onl
27b80 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 y return a gener
27b90 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ic [SQLITE_ERROR
27ba0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a ] result code.**
27bb0 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 and the applica
27bc0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 tion would have
27bd0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 to make a second
27be0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
27bf0 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 3_reset()].** in
27c00 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 order to find t
27c10 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 he underlying ca
27c20 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c use of the probl
27c30 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 em. With the "v2
27c40 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 " prepare.** int
27c50 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 erfaces, the und
27c60 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 erlying reason f
27c70 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 or the error is
27c80 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
27c90 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a tely..** </li>.*
27ca0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 *.** <li>.** ^If
27cb0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 the specific va
27cc0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 lue bound to [pa
27cd0 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 rameter | host p
27ce0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 arameter] in the
27cf0 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 .** WHERE claus
27d00 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 e might influenc
27d10 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 e the choice of
27d20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 query plan for a
27d30 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 statement,.** t
27d40 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
27d50 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 t will be automa
27d60 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c tically recompil
27d70 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 ed, as if there
27d80 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 had been .** a s
27d90 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e chema change, on
27da0 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c the first [sql
27db0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c ite3_step()] cal
27dc0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 l following any
27dd0 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 change.** to the
27de0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
27df0 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 ext | bindings]
27e00 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 of that [paramet
27e10 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 er]. .** ^The sp
27e20 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 ecific value of
27e30 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 WHERE-clause [pa
27e40 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 rameter] might i
27e50 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a nfluence the .**
27e60 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 choice of query
27e70 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 plan if the par
27e80 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 ameter is the le
27e90 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 ft-hand side of
27ea0 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b a [LIKE].** or [
27eb0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f GLOB] operator o
27ec0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 r if the paramet
27ed0 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 er is compared t
27ee0 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c o an indexed col
27ef0 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b umn.** and the [
27f00 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 SQLITE_ENABLE_ST
27f10 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d AT3] compile-tim
27f20 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 e option is enab
27f30 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a led..** </li>.**
27f40 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 </ol>.*/.int sq
27f50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 lite3_prepare(.
27f60 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
27f70 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
27f80 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
27f90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
27fa0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
27fb0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 statement, UTF-8
27fc0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
27fd0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
27fe0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
27ff0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
28000 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
28010 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
28020 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
28030 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
28040 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
28050 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
28060 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
28070 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
28080 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
28090 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
280a0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
280b0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
280c0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
280d0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
280e0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
280f0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
28100 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
28110 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
28120 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
28130 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
28140 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
28150 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
28160 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
28170 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
28180 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
28190 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
281a0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
281b0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
281c0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
281d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
281e0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 repare16(. sqli
281f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
28200 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
28210 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
28220 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
28230 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
28240 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
28250 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
28260 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
28270 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
28280 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
28290 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
282a0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
282b0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
282c0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
282d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
282e0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
282f0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
28300 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
28310 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
28320 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
28330 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
28340 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
28350 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
28360 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
28370 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
28380 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
28390 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
283a0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
283b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
283c0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
283d0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
283e0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
283f0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
28400 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
28410 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
28420 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
28430 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
28440 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
28450 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
28460 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
28470 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 F: Retrieving St
28480 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d atement SQL.** M
28490 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
284a0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 tmt.**.** ^This
284b0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
284c0 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
284d0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f e a saved copy o
284e0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a f the original.*
284f0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 * SQL text used
28500 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 to create a [pre
28510 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
28520 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 if that stateme
28530 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c nt was.** compil
28540 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ed using either
28550 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
28560 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
28570 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
28580 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 )]..*/.const cha
28590 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 r *sqlite3_sql(s
285a0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
285b0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
285c0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
285d0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d If An SQL Statem
285e0 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 ent Writes The D
285f0 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f atabase.** METHO
28600 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
28610 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
28620 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
28630 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (X) interface re
28640 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d turns true (non-
28650 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 zero) if.** and
28660 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 only if the [pre
28670 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
28680 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 X makes no dire
28690 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a ct changes to.**
286a0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
286b0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
286c0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 e..**.** Note th
286d0 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d at [application-
286e0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
286f0 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 tions] or.** [vi
28700 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 rtual tables] mi
28710 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 ght change the d
28720 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 atabase indirect
28730 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 ly as a side eff
28740 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 ect. .** ^(For
28750 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 example, if an a
28760 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
28770 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 es a function "e
28780 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 val()" that .**
28790 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 calls [sqlite3_e
287a0 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 xec()], then the
287b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 following SQL s
287c0 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a tatement would.*
287d0 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 * change the dat
287e0 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 abase file throu
287f0 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a gh side-effects:
28800 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
28810 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 te><pre>.** S
28820 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 ELECT eval('DELE
28830 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f TE FROM t1') FRO
28840 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c M t2;.** </pre><
28850 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
28860 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 ** But because t
28870 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 he [SELECT] stat
28880 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 ement does not c
28890 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
288a0 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 se file.** direc
288b0 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d tly, sqlite3_stm
288c0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 t_readonly() wou
288d0 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 ld still return
288e0 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 true.)^.**.** ^T
288f0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 ransaction contr
28900 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 ol statements su
28910 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b ch as [BEGIN], [
28920 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 COMMIT], [ROLLBA
28930 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 CK],.** [SAVEPOI
28940 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 NT], and [RELEAS
28950 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 E] cause sqlite3
28960 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
28970 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c to return true,
28980 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 .** since the st
28990 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c atements themsel
289a0 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 ves do not actua
289b0 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 lly modify the d
289c0 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 atabase but.** r
289d0 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 ather they contr
289e0 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 ol the timing of
289f0 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 when other stat
28a00 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 ements modify th
28a10 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 e .** database.
28a20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 ^The [ATTACH] a
28a30 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 nd [DETACH] stat
28a40 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 ements also caus
28a50 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d e.** sqlite3_stm
28a60 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 t_readonly() to
28a70 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 return true sinc
28a80 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 e, while those s
28a90 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 tatements.** cha
28aa0 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 nge the configur
28ab0 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 ation of a datab
28ac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 ase connection,
28ad0 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 they do not make
28ae0 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 .** changes to
28af0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
28b00 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
28b10 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e s on disk..*/.in
28b20 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 t sqlite3_stmt_r
28b30 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f eadonly(sqlite3_
28b40 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
28b50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
28b60 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 etermine If A Pr
28b70 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
28b80 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a Has Been Reset.
28b90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
28ba0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
28bb0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f he sqlite3_stmt_
28bc0 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 busy(S) interfac
28bd0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 e returns true (
28be0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 non-zero) if the
28bf0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
28c00 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 atement] S has b
28c10 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c een stepped at l
28c20 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 east once using
28c30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
28c40 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 p(S)] but has ne
28c50 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d ither run to com
28c60 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 pletion (returne
28c70 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e d.** [SQLITE_DON
28c80 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 E] from [sqlite3
28c90 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a _step(S)]) nor.*
28ca0 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 * been reset usi
28cb0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
28cc0 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c t(S)]. ^The sql
28cd0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 ite3_stmt_busy(S
28ce0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 ).** interface r
28cf0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 eturns false if
28d00 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e S is a NULL poin
28d10 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f ter. If S is no
28d20 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 t a .** NULL poi
28d30 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 nter and is not
28d40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 a pointer to a v
28d50 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 alid [prepared s
28d60 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a tatement].** obj
28d70 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 ect, then the be
28d80 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
28d90 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 ned and probably
28da0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a undesirable..**
28db0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
28dc0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 ce can be used i
28dd0 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 n combination [s
28de0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 qlite3_next_stmt
28df0 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 ()].** to locate
28e00 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 all prepared st
28e10 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 atements associa
28e20 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 ted with a datab
28e30 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 ase .** connecti
28e40 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e on that are in n
28e50 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 eed of being res
28e60 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 et. This can be
28e70 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 used,.** for ex
28e80 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f ample, in diagno
28e90 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f stic routines to
28ea0 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 search for prep
28eb0 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 ared .** stateme
28ec0 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c nts that are hol
28ed0 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 ding a transacti
28ee0 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 on open..*/.int
28ef0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 sqlite3_stmt_bus
28f00 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 y(sqlite3_stmt*)
28f10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
28f20 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 F: Dynamically T
28f30 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 yped Value Objec
28f40 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b t.** KEYWORDS: {
28f50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
28f60 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 3_value} {unprot
28f70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
28f80 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 lue}.**.** SQLit
28f90 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 e uses the sqlit
28fa0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
28fb0 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c to represent all
28fc0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 values.** that
28fd0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e can be stored in
28fe0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c a database tabl
28ff0 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 e. SQLite uses d
29000 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a ynamic typing.**
29010 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 for the values
29020 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c it stores. ^Val
29030 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 ues stored in sq
29040 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
29050 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e cts.** can be in
29060 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 tegers, floating
29070 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 point values, s
29080 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f trings, BLOBs, o
29090 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e r NULL..**.** An
290a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
290b0 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 bject may be eit
290c0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 her "protected"
290d0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 or "unprotected"
290e0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 ..** Some interf
290f0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 aces require a p
29100 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
29110 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 _value. Other i
29120 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c nterfaces.** wil
29130 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 l accept either
29140 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 a protected or a
29150 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
29160 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 lite3_value..**
29170 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 Every interface
29180 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c that accepts sql
29190 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d ite3_value argum
291a0 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a ents specifies.*
291b0 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * whether or not
291c0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 it requires a p
291d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
291e0 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 _value. The.**
291f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 [sqlite3_value_d
29200 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 up()] interface
29210 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 can be used to c
29220 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a onstruct a new .
29230 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c ** protected sql
29240 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 ite3_value from
29250 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 an unprotected s
29260 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a qlite3_value..**
29270 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 .** The terms "p
29280 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 rotected" and "u
29290 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 nprotected" refe
292a0 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 r to whether or
292b0 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 not.** a mutex i
292c0 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 s held. An inte
292d0 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 rnal mutex is he
292e0 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 ld for a protect
292f0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
29300 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e lue object but n
29310 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 o mutex is held
29320 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 for an unprotect
29330 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
29340 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 lue object. If
29350 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
29360 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d ed to be single-
29370 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 threaded.** (wit
29380 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 h [SQLITE_THREAD
29390 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 SAFE=0] and with
293a0 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 [sqlite3_thread
293b0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e safe()] returnin
293c0 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 g 0).** or if SQ
293d0 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f Lite is run in o
293e0 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 ne of reduced mu
293f0 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 tex modes .** [S
29400 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
29410 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 GLETHREAD] or [S
29420 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
29430 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 TITHREAD].** the
29440 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 n there is no di
29450 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 stinction betwee
29460 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 n protected and
29470 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
29480 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
29490 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 ects and they ca
294a0 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 n be used interc
294b0 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 hangeably. Howe
294c0 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 ver,.** for maxi
294d0 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 mum code portabi
294e0 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d lity it is recom
294f0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c mended that appl
29500 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c ications.** stil
29510 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 l make the disti
29520 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 nction between p
29530 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 rotected and unp
29540 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
29550 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
29560 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 s even when not
29570 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 strictly require
29580 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
29590 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
295a0 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 cts that are pas
295b0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 sed as parameter
295c0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d s into the.** im
295d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
295e0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
295f0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
29600 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 ns] are protecte
29610 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 d..** ^The sqlit
29620 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
29630 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
29640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
29650 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f alue()] is unpro
29660 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f tected..** Unpro
29670 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
29680 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 alue objects may
29690 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 only be used wi
296a0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 th.** [sqlite3_r
296b0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 esult_value()] a
296c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 nd [sqlite3_bind
296d0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 _value()]..** Th
296e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
296f0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f _blob | sqlite3_
29700 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 value_type()] fa
29710 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 mily of.** inter
29720 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 faces require pr
29730 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
29740 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a value objects..*
29750 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
29760 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c Mem sqlite3_val
29770 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ue;../*.** CAPI3
29780 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f REF: SQL Functio
29790 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 n Context Object
297a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 .**.** The conte
297b0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 xt in which an S
297c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 QL function exec
297d0 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 utes is stored i
297e0 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f n an.** sqlite3_
297f0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 context object.
29800 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 ^A pointer to a
29810 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 n sqlite3_contex
29820 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 t object.** is a
29830 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 lways first para
29840 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 meter to [applic
29850 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
29860 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a L functions]..**
29870 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
29880 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
29890 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
298a0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 tion will pass t
298b0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 his.** pointer t
298c0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c hrough into call
298d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 s to [sqlite3_re
298e0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 sult_int | sqlit
298f0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a e3_result()],.**
29900 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 [sqlite3_aggreg
29910 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 ate_context()],
29920 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 [sqlite3_user_da
29930 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 ta()],.** [sqlit
29940 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 e3_context_db_ha
29950 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 ndle()], [sqlite
29960 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 3_get_auxdata()]
29970 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c ,.** and/or [sql
29980 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
29990 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ()]..*/.typedef
299a0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 struct sqlite3_c
299b0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 ontext sqlite3_c
299c0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ontext;../*.** C
299d0 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 API3REF: Binding
299e0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 Values To Prepa
299f0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a red Statements.*
29a00 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 * KEYWORDS: {hos
29a10 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f t parameter} {ho
29a20 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b st parameters} {
29a30 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e host parameter n
29a40 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ame}.** KEYWORDS
29a50 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 : {SQL parameter
29a60 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 } {SQL parameter
29a70 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 s} {parameter bi
29a80 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 nding}.** METHOD
29a90 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
29aa0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 *.** ^(In the SQ
29ab0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 L statement text
29ac0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
29ad0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
29ae0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 and its variant
29af0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d s,.** literals m
29b00 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 ay be replaced b
29b10 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 y a [parameter]
29b20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 that matches one
29b30 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a of following.**
29b40 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a templates:.**.*
29b50 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 * <ul>.** <li>
29b60 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a ?.** <li> ?NNN.
29b70 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a ** <li> :VVV.**
29b80 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c <li> @VVV.** <
29b90 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 li> $VVV.** </u
29ba0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 l>.**.** In the
29bb0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c templates above,
29bc0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 NNN represents
29bd0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 an integer liter
29be0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 al,.** and VVV r
29bf0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 epresents an alp
29c00 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 hanumeric identi
29c10 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 fier.)^ ^The va
29c20 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a lues of these.**
29c30 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 parameters (als
29c40 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 o called "host p
29c50 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 arameter names"
29c60 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 or "SQL paramete
29c70 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 rs").** can be s
29c80 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c et using the sql
29c90 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f ite3_bind_*() ro
29ca0 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 utines defined h
29cb0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ere..**.** ^The
29cc0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
29cd0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 o the sqlite3_bi
29ce0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
29cf0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 is always.** a p
29d00 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ointer to the [s
29d10 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a qlite3_stmt] obj
29d20 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f ect returned fro
29d30 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 m.** [sqlite3_pr
29d40 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 epare_v2()] or i
29d50 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a ts variants..**.
29d60 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 ** ^The second a
29d70 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 rgument is the i
29d80 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 ndex of the SQL
29d90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 parameter to be
29da0 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 set..** ^The lef
29db0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 tmost SQL parame
29dc0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 ter has an index
29dd0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 of 1. ^When th
29de0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 e same named.**
29df0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 SQL parameter is
29e00 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 used more than
29e10 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 once, second and
29e20 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f subsequent.** o
29e30 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 ccurrences have
29e40 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 the same index a
29e50 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 s the first occu
29e60 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 rrence..** ^The
29e70 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 index for named
29e80 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 parameters can b
29e90 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e e looked up usin
29ea0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
29eb0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
29ec0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 _index()] API if
29ed0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 desired. ^The
29ee0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e index.** for "?N
29ef0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 NN" parameters i
29f00 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e s the value of N
29f10 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 NN..** ^The NNN
29f20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 value must be be
29f30 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 tween 1 and the
29f40 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
29f50 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b ].** parameter [
29f60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
29f70 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 IABLE_NUMBER] (d
29f80 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 efault value: 99
29f90 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 9)..**.** ^The t
29fa0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
29fb0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 the value to bi
29fc0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 nd to the parame
29fd0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ter..** ^If the
29fe0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
29ff0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f to sqlite3_bind_
2a000 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 text() or sqlite
2a010 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 3_bind_text16().
2a020 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 ** or sqlite3_bi
2a030 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e nd_blob() is a N
2a040 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
2a050 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
2a060 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f meter.** is igno
2a070 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 red and the end
2a080 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 result is the sa
2a090 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 me as sqlite3_bi
2a0a0 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a nd_null()..**.**
2a0b0 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 ^(In those rout
2a0c0 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 ines that have a
2a0d0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
2a0e0 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 , its value is t
2a0f0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
2a100 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 bytes in the par
2a110 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 ameter. To be c
2a120 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 lear: the value
2a130 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 is the.** number
2a140 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e of <u>bytes</u>
2a150 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e in the value, n
2a160 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ot the number of
2a170 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a characters.)^.*
2a180 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 * ^If the fourth
2a190 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
2a1a0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
2a1b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e ) or sqlite3_bin
2a1c0 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 d_text16().** is
2a1d0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
2a1e0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 the length of th
2a1f0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 e string is.** t
2a200 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
2a210 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 es up to the fir
2a220 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 st zero terminat
2a230 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f or..** If the fo
2a240 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
2a250 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 o sqlite3_bind_b
2a260 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 lob() is negativ
2a270 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 e, then.** the b
2a280 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
2a290 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f ined..** If a no
2a2a0 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 n-negative fourt
2a2b0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 h parameter is p
2a2c0 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 rovided to sqlit
2a2d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a e3_bind_text().*
2a2e0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e * or sqlite3_bin
2a2f0 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 d_text16() or sq
2a300 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 lite3_bind_text6
2a310 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 4() then.** that
2a320 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 parameter must
2a330 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 be the byte offs
2a340 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 et.** where the
2a350 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 NUL terminator w
2a360 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d ould occur assum
2a370 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 ing the string w
2a380 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 ere NUL.** termi
2a390 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e nated. If any N
2a3a0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 UL characters oc
2a3b0 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 cur at byte offs
2a3c0 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a ets less than .*
2a3d0 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 * the value of t
2a3e0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
2a3f0 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 ter then the res
2a400 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 ulting string va
2a410 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 lue will.** cont
2a420 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c ain embedded NUL
2a430 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f s. The result o
2a440 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e f expressions in
2a450 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a volving strings.
2a460 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 ** with embedded
2a470 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e NULs is undefin
2a480 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ed..**.** ^The f
2a490 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f ifth argument to
2a4a0 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 the BLOB and st
2a4b0 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 ring binding int
2a4c0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 erfaces.** is a
2a4d0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 destructor used
2a4e0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 to dispose of th
2a4f0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 e BLOB or.** str
2a500 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 ing after SQLite
2a510 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
2a520 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 th it. ^The des
2a530 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 tructor is calle
2a540 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 d.** to dispose
2a550 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 of the BLOB or s
2a560 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 tring even if th
2a570 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 e call to bind A
2a580 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 PI fails..** ^If
2a590 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d the fifth argum
2a5a0 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 ent is.** the sp
2a5b0 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c ecial value [SQL
2a5c0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 ITE_STATIC], the
2a5d0 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 n SQLite assumes
2a5e0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 that the.** inf
2a5f0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 ormation is in s
2a600 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 tatic, unmanaged
2a610 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 space and does
2a620 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 not need to be f
2a630 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 reed..** ^If the
2a640 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 fifth argument
2a650 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 has the value [S
2a660 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d QLITE_TRANSIENT]
2a670 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 , then.** SQLite
2a680 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 makes its own p
2a690 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 rivate copy of t
2a6a0 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 he data immediat
2a6b0 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 ely, before.** t
2a6c0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
2a6d0 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 *() routine retu
2a6e0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rns..**.** ^The
2a6f0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 sixth argument t
2a700 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
2a710 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 ext64() must be
2a720 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 one of.** [SQLIT
2a730 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 E_UTF8], [SQLITE
2a740 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 _UTF16], [SQLITE
2a750 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 _UTF16BE], or [S
2a760 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a QLITE_UTF16LE].*
2a770 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 * to specify the
2a780 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 encoding of the
2a790 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 text in the thi
2a7a0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 rd parameter. I
2a7b0 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 f.** the sixth a
2a7c0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
2a7d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 e3_bind_text64()
2a7e0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 is not one of t
2a7f0 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 he.** allowed va
2a800 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 lues shown above
2a810 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 , or if the text
2a820 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 encoding is dif
2a830 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 ferent.** from t
2a840 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 he encoding spec
2a850 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 ified by the six
2a860 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 th parameter, th
2a870 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a en the behavior.
2a880 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e ** is undefined.
2a890 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2a8a0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f te3_bind_zeroblo
2a8b0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 b() routine bind
2a8c0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 s a BLOB of leng
2a8d0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 th N that.** is
2a8e0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f filled with zero
2a8f0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 es. ^A zeroblob
2a900 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d uses a fixed am
2a910 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a ount of memory.*
2a920 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 * (just an integ
2a930 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 er to hold its s
2a940 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 ize) while it is
2a950 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 being processed
2a960 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 ..** Zeroblobs a
2a970 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 re intended to s
2a980 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c erve as placehol
2a990 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 ders for BLOBs w
2a9a0 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 hose.** content
2a9b0 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e is later written
2a9c0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
2a9d0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 e3_blob_open | i
2a9e0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 ncremental BLOB
2a9f0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a I/O] routines..*
2aa00 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 * ^A negative va
2aa10 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f lue for the zero
2aa20 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 blob results in
2aa30 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c a zero-length BL
2aa40 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e OB..**.** ^If an
2aa50 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 y of the sqlite3
2aa60 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
2aa70 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 es are called wi
2aa80 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
2aa90 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 r.** for the [pr
2aaa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2aab0 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 ] or with a prep
2aac0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 ared statement f
2aad0 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c or which.** [sql
2aae0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
2aaf0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 been called mor
2ab00 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 e recently than
2ab10 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2ab20 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 ],.** then the c
2ab30 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 all will return
2ab40 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e [SQLITE_MISUSE].
2ab50 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 If any sqlite3
2ab60 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 _bind_().** rout
2ab70 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 ine is passed a
2ab80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2ab90 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 ent] that has be
2aba0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 en finalized, th
2abb0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 e.** result is u
2abc0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
2abd0 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a bably harmful..*
2abe0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 *.** ^Bindings a
2abf0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 re not cleared b
2ac00 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 y the [sqlite3_r
2ac10 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e eset()] routine.
2ac20 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 .** ^Unbound par
2ac30 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 ameters are inte
2ac40 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e rpreted as NULL.
2ac50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2ac60 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 te3_bind_* routi
2ac70 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 nes return [SQLI
2ac80 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
2ac90 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f s or an.** [erro
2aca0 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 r code] if anyth
2acb0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a ing goes wrong..
2acc0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 ** ^[SQLITE_TOOB
2acd0 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 IG] might be ret
2ace0 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a urned if the siz
2acf0 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 e of a string or
2ad00 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 BLOB.** exceeds
2ad10 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 limits imposed
2ad20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 by [sqlite3_limi
2ad30 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 t]([SQLITE_LIMIT
2ad40 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 _LENGTH]) or.**
2ad50 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 [SQLITE_MAX_LENG
2ad60 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 TH]..** ^[SQLITE
2ad70 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 _RANGE] is retur
2ad80 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d ned if the param
2ad90 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 eter.** index is
2ada0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 out of range.
2adb0 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 ^[SQLITE_NOMEM]
2adc0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d is returned if m
2add0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a alloc() fails..*
2ade0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2adf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2ae00 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
2ae10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2ae20 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
2ae30 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
2ae40 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2ae50 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e _index()]..*/.in
2ae60 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 t sqlite3_bind_b
2ae70 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
2ae80 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f *, int, const vo
2ae90 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 id*, int n, void
2aea0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 (*)(void*));.int
2aeb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
2aec0 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d ob64(sqlite3_stm
2aed0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 t*, int, const v
2aee0 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 oid*, sqlite3_ui
2aef0 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 nt64,.
2af00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f vo
2af10 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
2af20 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2af30 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 double(sqlite3_s
2af40 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c tmt*, int, doubl
2af50 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f e);.int sqlite3_
2af60 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 bind_int(sqlite3
2af70 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
2af80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
2af90 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 ind_int64(sqlite
2afa0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 3_stmt*, int, sq
2afb0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e lite3_int64);.in
2afc0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e t sqlite3_bind_n
2afd0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ull(sqlite3_stmt
2afe0 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c *, int);.int sql
2aff0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 ite3_bind_text(s
2b000 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2b010 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 ,const char*,int
2b020 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 ,void(*)(void*))
2b030 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
2b040 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 nd_text16(sqlite
2b050 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
2b060 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 nst void*, int,
2b070 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
2b080 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
2b090 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 d_text64(sqlite3
2b0a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
2b0b0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 st char*, sqlite
2b0c0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 3_uint64,.
2b0d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2b0e0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a void(*)(void*
2b0f0 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 ), unsigned char
2b100 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 encoding);.int
2b110 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c sqlite3_bind_val
2b120 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ue(sqlite3_stmt*
2b130 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c , int, const sql
2b140 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e ite3_value*);.in
2b150 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a t sqlite3_bind_z
2b160 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f eroblob(sqlite3_
2b170 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 stmt*, int, int
2b180 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f n);.int sqlite3_
2b190 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 bind_zeroblob64(
2b1a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2b1b0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 nt, sqlite3_uint
2b1c0 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 64);../*.** CAPI
2b1d0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
2b1e0 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a SQL Parameters.*
2b1f0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
2b200 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
2b210 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 is routine can b
2b220 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 e used to find t
2b230 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 he number of [SQ
2b240 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a L parameters].**
2b250 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 in a [prepared
2b260 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c statement]. SQL
2b270 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 parameters are
2b280 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a tokens of the.**
2b290 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e form "?", "?NNN
2b2a0 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 ", ":AAA", "$AAA
2b2b0 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 ", or "@AAA" tha
2b2c0 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c t serve as.** pl
2b2d0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 aceholders for v
2b2e0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b alues that are [
2b2f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2b300 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f b | bound].** to
2b310 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 the parameters
2b320 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e at a later time.
2b330 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f .**.** ^(This ro
2b340 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 utine actually r
2b350 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 eturns the index
2b360 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 of the largest
2b370 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 (rightmost).** p
2b380 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c arameter. For al
2b390 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f l forms except ?
2b3a0 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 NNN, this will c
2b3b0 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 orrespond to the
2b3c0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e .** number of un
2b3d0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e ique parameters.
2b3e0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 If parameters
2b3f0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d of the ?NNN form
2b400 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 are used,.** th
2b410 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 ere may be gaps
2b420 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a in the list.)^.*
2b430 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2b440 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2b450 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
2b460 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
2b470 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
2b480 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 me()], and.** [s
2b490 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2b4a0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
2b4b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
2b4c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
2b4d0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
2b4e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
2b4f0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 REF: Name Of A H
2b500 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a ost Parameter.**
2b510 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2b520 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _stmt.**.** ^The
2b530 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 sqlite3_bind_pa
2b540 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e rameter_name(P,N
2b550 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2b560 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 rns.** the name
2b570 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c of the N-th [SQL
2b580 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 parameter] in t
2b590 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2b5a0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 tement] P..** ^(
2b5b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f SQL parameters o
2b5c0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e f the form "?NNN
2b5d0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 " or ":AAA" or "
2b5e0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a @AAA" or "$AAA".
2b5f0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 ** have a name w
2b600 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 hich is the stri
2b610 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 ng "?NNN" or ":A
2b620 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 AA" or "@AAA" or
2b630 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 "$AAA".** respe
2b640 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f ctively..** In o
2b650 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
2b660 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 initial ":" or "
2b670 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 $" or "@" or "?"
2b680 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 .** is included
2b690 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e as part of the n
2b6a0 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d ame.)^.** ^Param
2b6b0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 eters of the for
2b6c0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 m "?" without a
2b6d0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 following intege
2b6e0 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a r have no name.*
2b6f0 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 * and are referr
2b700 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 ed to as "namele
2b710 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 ss" or "anonymou
2b720 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a s parameters"..*
2b730 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
2b740 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 host parameter h
2b750 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 as an index of 1
2b760 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e , not 0..**.** ^
2b770 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 If the value N i
2b780 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f s out of range o
2b790 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 r if the N-th pa
2b7a0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 rameter is.** na
2b7b0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c meless, then NUL
2b7c0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 L is returned.
2b7d0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 ^The returned st
2b7e0 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 ring is.** alway
2b7f0 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 s in UTF-8 encod
2b800 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 ing even if the
2b810 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 named parameter
2b820 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c was.** originall
2b830 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 y specified as U
2b840 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 TF-16 in [sqlite
2b850 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 3_prepare16()] o
2b860 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 r.** [sqlite3_pr
2b870 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a epare16_v2()]..*
2b880 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2b890 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2b8a0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
2b8b0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
2b8c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
2b8d0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b unt()], and.** [
2b8e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2b8f0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
2b900 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
2b910 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2b920 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 ameter_name(sqli
2b930 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b te3_stmt*, int);
2b940 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2b950 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 : Index Of A Par
2b960 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 ameter With A Gi
2b970 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 ven Name.** METH
2b980 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2b990 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 .**.** ^Return t
2b9a0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 he index of an S
2b9b0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 QL parameter giv
2b9c0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 en its name. ^T
2b9d0 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 he.** index valu
2b9e0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 e returned is su
2b9f0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 itable for use a
2ba00 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 s the second.**
2ba10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
2ba20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
2ba30 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e sqlite3_bind()].
2ba40 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 ^A zero.** is
2ba50 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d returned if no m
2ba60 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 atching paramete
2ba70 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 r is found. ^Th
2ba80 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e e parameter.** n
2ba90 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 ame must be give
2baa0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 n in UTF-8 even
2bab0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 if the original
2bac0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 statement.** was
2bad0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 prepared from U
2bae0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 TF-16 text using
2baf0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2bb00 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a e16_v2()]..**.**
2bb10 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
2bb20 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
2bb30 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a lite3_bind()],.*
2bb40 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2bb50 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
2bb60 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
2bb70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2bb80 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a er_index()]..*/.
2bb90 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2bba0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
2bbb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2bbc0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
2bbd0 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 e);../*.** CAPI3
2bbe0 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 REF: Reset All B
2bbf0 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 indings On A Pre
2bc00 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a pared Statement.
2bc10 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2bc20 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 e3_stmt.**.** ^C
2bc30 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 ontrary to the i
2bc40 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 ntuition of many
2bc50 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 , [sqlite3_reset
2bc60 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 ()] does not res
2bc70 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 et.** the [sqlit
2bc80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
2bc90 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 indings] on a [p
2bca0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2bcb0 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 t]..** ^Use this
2bcc0 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 routine to rese
2bcd0 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d t all host param
2bce0 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a eters to NULL..*
2bcf0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c /.int sqlite3_cl
2bd00 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c ear_bindings(sql
2bd10 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
2bd20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
2bd30 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 mber Of Columns
2bd40 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a In A Result Set.
2bd50 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2bd60 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 e3_stmt.**.** ^R
2bd70 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 eturn the number
2bd80 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
2bd90 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 he result set re
2bda0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a turned by the.**
2bdb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2bdc0 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 ment]. ^This rou
2bdd0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 tine returns 0 i
2bde0 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 f pStmt is an SQ
2bdf0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 L.** statement t
2be00 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 hat does not ret
2be10 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 urn data (for ex
2be20 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 ample an [UPDATE
2be30 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ])..**.** See al
2be40 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 so: [sqlite3_dat
2be50 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e a_count()].*/.in
2be60 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
2be70 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
2be80 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
2be90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
2bea0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 lumn Names In A
2beb0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 Result Set.** ME
2bec0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2bed0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 mt.**.** ^These
2bee0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
2bef0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 the name assigne
2bf00 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 d to a particula
2bf10 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 r column.** in t
2bf20 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 he result set of
2bf30 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 a [SELECT] stat
2bf40 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c ement. ^The sql
2bf50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
2bf60 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
2bf70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
2bf80 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
2bf90 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
2bfa0 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 ing.** and sqlit
2bfb0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
2bfc0 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 () returns a poi
2bfd0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 nter to a zero-t
2bfe0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
2bff0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 -16 string. ^Th
2c000 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
2c010 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 r is the [prepar
2c020 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
2c030 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 that implements
2c040 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 the [SELECT] st
2c050 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 atement. ^The se
2c060 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
2c070 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 s the.** column
2c080 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 number. ^The le
2c090 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 ftmost column is
2c0a0 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a number 0..**.**
2c0b0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
2c0c0 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 tring pointer is
2c0d0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 valid until eit
2c0e0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 her the [prepare
2c0f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
2c100 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 is destroyed by
2c110 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2c120 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 e()] or until th
2c130 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
2c140 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 utomatically.**
2c150 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 reprepared by th
2c160 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 e first call to
2c170 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2c180 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
2c190 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 r run.** or unti
2c1a0 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 l the next call
2c1b0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f to.** sqlite3_co
2c1c0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 lumn_name() or s
2c1d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
2c1e0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 me16() on the sa
2c1f0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a me column..**.**
2c200 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^If sqlite3_mal
2c210 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 loc() fails duri
2c220 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e ng the processin
2c230 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 g of either rout
2c240 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d ine.** (for exam
2c250 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e ple during a con
2c260 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 version from UTF
2c270 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 -8 to UTF-16) th
2c280 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 en a.** NULL poi
2c290 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 nter is returned
2c2a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d ..**.** ^The nam
2c2b0 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f e of a result co
2c2c0 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 lumn is the valu
2c2d0 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c e of the "AS" cl
2c2e0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 ause for.** that
2c2f0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 column, if ther
2c300 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 e is an AS claus
2c310 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 e. If there is
2c320 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 no AS clause.**
2c330 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 then the name of
2c340 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 the column is u
2c350 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d nspecified and m
2c360 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a ay change from.*
2c370 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 * one release of
2c380 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e SQLite to the n
2c390 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ext..*/.const ch
2c3a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
2c3b0 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f mn_name(sqlite3_
2c3c0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 stmt*, int N);.c
2c3d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
2c3e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
2c3f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2c400 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int N);../*.** C
2c410 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 API3REF: Source
2c420 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 Of Data In A Que
2c430 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 ry Result.** MET
2c440 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
2c450 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 t.**.** ^These r
2c460 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 outines provide
2c470 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 a means to deter
2c480 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 mine the databas
2c490 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a e, table, and.**
2c4a0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 table column th
2c4b0 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e at is the origin
2c4c0 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 of a particular
2c4d0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 result column i
2c4e0 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 n.** [SELECT] st
2c4f0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 atement..** ^The
2c500 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
2c510 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f abase or table o
2c520 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 r column can be
2c530 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 returned as.** e
2c540 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 ither a UTF-8 or
2c550 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 UTF-16 string.
2c560 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f ^The _database_
2c570 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2c580 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
2c590 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c name, the _tabl
2c5a0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 e_ routines retu
2c5b0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d rn the table nam
2c5c0 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 e, and.** the or
2c5d0 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 igin_ routines r
2c5e0 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e eturn the column
2c5f0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 name..** ^The r
2c600 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
2c610 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 s valid until th
2c620 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2c630 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f ement] is destro
2c640 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 yed.** using [sq
2c650 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2c660 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 ] or until the s
2c670 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f tatement is auto
2c680 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 matically.** rep
2c690 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 repared by the f
2c6a0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 irst call to [sq
2c6b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f lite3_step()] fo
2c6c0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 r a particular r
2c6d0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 un.** or until t
2c6e0 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 he same informat
2c6f0 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 ion is requested
2c700 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 .** again in a d
2c710 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e ifferent encodin
2c720 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 g..**.** ^The na
2c730 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 mes returned are
2c740 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e the original un
2c750 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f -aliased names o
2c760 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 f the.** databas
2c770 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f e, table, and co
2c780 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 lumn..**.** ^The
2c790 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
2c7a0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 to these interfa
2c7b0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 ces is a [prepar
2c7c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
2c7d0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f * ^These functio
2c7e0 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d ns return inform
2c7f0 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 ation about the
2c800 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d Nth result colum
2c810 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a n returned by.**
2c820 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 the statement,
2c830 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 where N is the s
2c840 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 econd function a
2c850 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 rgument..** ^The
2c860 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d left-most colum
2c870 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f n is column 0 fo
2c880 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 r these routines
2c890 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
2c8a0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 Nth column retur
2c8b0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 ned by the state
2c8c0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 ment is an expre
2c8d0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 ssion or.** subq
2c8e0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 uery and is not
2c8f0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 a column value,
2c900 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 then all of thes
2c910 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
2c920 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 rn.** NULL. ^Th
2c930 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 ese routine migh
2c940 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 t also return NU
2c950 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 LL if a memory a
2c960 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a llocation error.
2c970 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 ** occurs. ^Oth
2c980 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 erwise, they ret
2c990 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 urn the name of
2c9a0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 the attached dat
2c9b0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a abase, table,.**
2c9c0 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 or column that
2c9d0 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c query result col
2c9e0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 umn was extracte
2c9f0 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 d from..**.** ^A
2ca00 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 s with all other
2ca10 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 SQLite APIs, th
2ca20 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 ose whose names
2ca30 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 end with "16" re
2ca40 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 turn.** UTF-16 e
2ca50 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 ncoded strings a
2ca60 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e nd the other fun
2ca70 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 ctions return UT
2ca80 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 F-8..**.** ^Thes
2ca90 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 e APIs are only
2caa0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 available if the
2cab0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d library was com
2cac0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
2cad0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 * [SQLITE_ENABLE
2cae0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 _COLUMN_METADATA
2caf0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C-preprocessor
2cb00 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 symbol..**.** I
2cb10 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 f two or more th
2cb20 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f reads call one o
2cb30 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 r more of these
2cb40 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 routines against
2cb50 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 the same.** pre
2cb60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
2cb70 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 and column at th
2cb80 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e e same time then
2cb90 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
2cba0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a .** undefined..*
2cbb0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d *.** If two or m
2cbc0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c ore threads call
2cbd0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
2cbe0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2cbf0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 database_name |
2cc00 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 column metadata
2cc10 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 interfaces].** f
2cc20 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 or the same [pre
2cc30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2cc40 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 and result colu
2cc50 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d mn.** at the sam
2cc60 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 e time then the
2cc70 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
2cc80 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 fined..*/.const
2cc90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
2cca0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
2ccb0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
2ccc0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
2ccd0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
2cce0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 n_database_name1
2ccf0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
2cd00 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 int);.const char
2cd10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
2cd20 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 _table_name(sqli
2cd30 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
2cd40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
2cd50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 te3_column_table
2cd60 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
2cd70 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
2cd80 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
2cd90 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
2cda0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
2cdb0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
2cdc0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
2cdd0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 n_origin_name16(
2cde0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2cdf0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2ce00 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 REF: Declared Da
2ce10 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 tatype Of A Quer
2ce20 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 y Result.** METH
2ce30 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2ce40 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 .**.** ^(The fir
2ce50 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
2ce60 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2ce70 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 ement]..** If th
2ce80 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 is statement is
2ce90 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 a [SELECT] state
2cea0 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 ment and the Nth
2ceb0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a column of the.*
2cec0 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c * returned resul
2ced0 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 t set of that [S
2cee0 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c ELECT] is a tabl
2cef0 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e e column (not an
2cf00 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f .** expression o
2cf10 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e r subquery) then
2cf20 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 the declared ty
2cf30 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a pe of the table.
2cf40 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 ** column is ret
2cf50 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 urned.)^ ^If th
2cf60 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 e Nth column of
2cf70 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 the result set i
2cf80 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 s an.** expressi
2cf90 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 on or subquery,
2cfa0 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e then a NULL poin
2cfb0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ter is returned.
2cfc0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 .** ^The returne
2cfd0 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 d string is alwa
2cfe0 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 ys UTF-8 encoded
2cff0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 ..**.** ^(For ex
2d000 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 ample, given the
2d010 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 database schema
2d020 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 :.**.** CREATE T
2d030 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 ABLE t1(c1 VARIA
2d040 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 NT);.**.** and t
2d050 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 he following sta
2d060 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d tement to be com
2d070 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c piled:.**.** SEL
2d080 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 ECT c1 + 1, c1 F
2d090 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 ROM t1;.**.** th
2d0a0 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 is routine would
2d0b0 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 return the stri
2d0c0 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 ng "VARIANT" for
2d0d0 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 the second resu
2d0e0 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d lt.** column (i=
2d0f0 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 =1), and a NULL
2d100 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 pointer for the
2d110 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c first result col
2d120 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a umn (i==0).)^.**
2d130 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 .** ^SQLite uses
2d140 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d dynamic run-tim
2d150 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a e typing. ^So j
2d160 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f ust because a co
2d170 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 lumn.** is decla
2d180 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 red to contain a
2d190 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 particular type
2d1a0 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 does not mean t
2d1b0 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 hat the.** data
2d1c0 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 stored in that c
2d1d0 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 olumn is of the
2d1e0 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 declared type.
2d1f0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 SQLite is.** str
2d200 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 ongly typed, but
2d210 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 the typing is d
2d220 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 ynamic not stati
2d230 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 c. ^Type.** is
2d240 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
2d250 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 individual value
2d260 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 s, not with the
2d270 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 containers.** us
2d280 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 ed to hold those
2d290 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 values..*/.cons
2d2a0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
2d2b0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 column_decltype(
2d2c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2d2d0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a t);.const void *
2d2e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
2d2f0 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 ecltype16(sqlite
2d300 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 3_stmt*,int);../
2d310 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
2d320 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 valuate An SQL S
2d330 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 tatement.** METH
2d340 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2d350 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b .**.** After a [
2d360 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2d370 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 nt] has been pre
2d380 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 pared using eith
2d390 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 er.** [sqlite3_p
2d3a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
2d3b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2d3c0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 16_v2()] or one
2d3d0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a of the legacy.**
2d3e0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c interfaces [sql
2d3f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
2d400 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
2d410 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 are16()], this f
2d420 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 unction.** must
2d430 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 be called one or
2d440 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 more times to e
2d450 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 valuate the stat
2d460 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ement..**.** The
2d470 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 details of the
2d480 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 behavior of the
2d490 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
2d4a0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a nterface depend.
2d4b0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 ** on whether th
2d4c0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 e statement was
2d4d0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 prepared using t
2d4e0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e he newer "v2" in
2d4f0 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 terface.** [sqli
2d500 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2d510 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
2d520 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f repare16_v2()] o
2d530 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 r the older lega
2d540 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 cy.** interface
2d550 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2d560 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2d570 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 _prepare16()].
2d580 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a The use of the.*
2d590 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 * new "v2" inter
2d5a0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
2d5b0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c ded for new appl
2d5c0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 ications but the
2d5d0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 legacy.** inter
2d5e0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e face will contin
2d5f0 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ue to be support
2d600 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 ed..**.** ^In th
2d610 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 e legacy interfa
2d620 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 ce, the return v
2d630 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 alue will be eit
2d640 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 her [SQLITE_BUSY
2d650 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f ],.** [SQLITE_DO
2d660 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 NE], [SQLITE_ROW
2d670 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ], [SQLITE_ERROR
2d680 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 ], or [SQLITE_MI
2d690 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 SUSE]..** ^With
2d6a0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2d6b0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f ce, any of the o
2d6c0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 ther [result cod
2d6d0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e es] or.** [exten
2d6e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
2d6f0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 ] might be retur
2d700 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a ned as well..**.
2d710 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 ** ^[SQLITE_BUSY
2d720 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
2d730 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 database engine
2d740 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 was unable to a
2d750 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 cquire the.** da
2d760 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 tabase locks it
2d770 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 needs to do its
2d780 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 job. ^If the st
2d790 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f atement is a [CO
2d7a0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 MMIT].** or occu
2d7b0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e rs outside of an
2d7c0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
2d7d0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 ction, then you
2d7e0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a can retry the.**
2d7f0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 statement. If
2d800 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
2d810 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 not a [COMMIT]
2d820 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 and occurs withi
2d830 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 n an.** explicit
2d840 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 transaction the
2d850 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c n you should rol
2d860 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 lback the transa
2d870 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 ction before.**
2d880 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a continuing..**.*
2d890 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d * ^[SQLITE_DONE]
2d8a0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
2d8b0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 statement has fi
2d8c0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 nished executing
2d8d0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 .** successfully
2d8e0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 . sqlite3_step(
2d8f0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ) should not be
2d900 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 called again on
2d910 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 this virtual.**
2d920 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 machine without
2d930 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 first calling [s
2d940 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2d950 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 to reset the vir
2d960 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 tual.** machine
2d970 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 back to its init
2d980 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a ial state..**.**
2d990 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 ^If the SQL sta
2d9a0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 tement being exe
2d9b0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e cuted returns an
2d9c0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 y data, then [SQ
2d9d0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 LITE_ROW].** is
2d9e0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 returned each ti
2d9f0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 me a new row of
2da00 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f data is ready fo
2da10 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 r processing by
2da20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 the.** caller. T
2da30 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 he values may be
2da40 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 accessed using
2da50 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 the [column acce
2da60 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a ss functions]..*
2da70 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
2da80 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e is called again
2da90 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 to retrieve the
2daa0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 next row of dat
2dab0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 a..**.** ^[SQLIT
2dac0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 E_ERROR] means t
2dad0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 hat a run-time e
2dae0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 rror (such as a
2daf0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 constraint.** vi
2db00 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 olation) has occ
2db10 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f urred. sqlite3_
2db20 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f step() should no
2db30 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 t be called agai
2db40 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 n on.** the VM.
2db50 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e More information
2db60 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 may be found by
2db70 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
2db80 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 3_errmsg()]..**
2db90 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 ^With the legacy
2dba0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f interface, a mo
2dbb0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f re specific erro
2dbc0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d r code (for exam
2dbd0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ple,.** [SQLITE_
2dbe0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c INTERRUPT], [SQL
2dbf0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 ITE_SCHEMA], [SQ
2dc00 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 LITE_CORRUPT], a
2dc10 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 nd so forth).**
2dc20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 can be obtained
2dc30 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
2dc40 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 te3_reset()] on
2dc50 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
2dc60 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 statement]. ^I
2dc70 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 n the "v2" inter
2dc80 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 face,.** the mor
2dc90 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 e specific error
2dca0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 code is returne
2dcb0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 d directly by sq
2dcc0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a lite3_step()..**
2dcd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 .** [SQLITE_MISU
2dce0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 SE] means that t
2dcf0 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 he this routine
2dd00 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 was called inapp
2dd10 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 ropriately..** P
2dd20 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 erhaps it was ca
2dd30 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 lled on a [prepa
2dd40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
2dd50 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 hat has.** alrea
2dd60 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 dy been [sqlite3
2dd70 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 _finalize | fina
2dd80 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 lized] or on one
2dd90 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 that had.** pre
2dda0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 viously returned
2ddb0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
2ddc0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d or [SQLITE_DONE]
2ddd0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a . Or it could.*
2dde0 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 * be the case th
2ddf0 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 at the same data
2de00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2de10 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 is being used by
2de20 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 two or.** more
2de30 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 threads at the s
2de40 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 ame moment in ti
2de50 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c me..**.** For al
2de60 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 l versions of SQ
2de70 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 Lite up to and i
2de80 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e ncluding 3.6.23.
2de90 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 1, a call to.**
2dea0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2deb0 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 ] was required a
2dec0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 fter sqlite3_ste
2ded0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 p() returned any
2dee0 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 thing.** other t
2def0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d han [SQLITE_ROW]
2df00 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 before any subs
2df10 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f equent invocatio
2df20 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f n of.** sqlite3_
2df30 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 step(). Failure
2df40 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 to reset the pr
2df50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2df60 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 using .** [sqli
2df70 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 te3_reset()] wou
2df80 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 ld result in an
2df90 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
2dfa0 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 return from.** s
2dfb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
2dfc0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f But after versio
2dfd0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 n 3.6.23.1, sqli
2dfe0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e te3_step() began
2dff0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c .** calling [sql
2e000 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 ite3_reset()] au
2e010 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 tomatically in t
2e020 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 his circumstance
2e030 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 rather.** than
2e040 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 returning [SQLIT
2e050 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 E_MISUSE]. This
2e060 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 is not consider
2e070 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 ed a compatibili
2e080 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 ty.** break beca
2e090 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 use any applicat
2e0a0 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 ion that ever re
2e0b0 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 ceives an SQLITE
2e0c0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a _MISUSE error.**
2e0d0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 is broken by de
2e0e0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b finition. The [
2e0f0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
2e100 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 RESET] compile-t
2e110 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 ime option.** ca
2e120 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 n be used to res
2e130 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 tore the legacy
2e140 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 behavior..**.**
2e150 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 <b>Goofy Interfa
2e160 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e ce Alert:</b> In
2e170 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
2e180 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 rface, the sqlit
2e190 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 e3_step().** API
2e1a0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
2e1b0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 a generic error
2e1c0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 code, [SQLITE_ER
2e1d0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 ROR], following
2e1e0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 any.** error oth
2e1f0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
2e200 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 BUSY] and [SQLIT
2e210 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 E_MISUSE]. You
2e220 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 must call.** [sq
2e230 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
2e240 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
2e250 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 ize()] in order
2e260 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 to find one of t
2e270 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b he.** specific [
2e280 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 error codes] tha
2e290 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 t better describ
2e2a0 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a es the error..**
2e2b0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 We admit that t
2e2c0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 his is a goofy d
2e2d0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 esign. The prob
2e2e0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 lem has been fix
2e2f0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 ed.** with the "
2e300 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 v2" interface.
2e310 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 If you prepare a
2e320 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 ll of your SQL s
2e330 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 tatements.** usi
2e340 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 ng either [sqlit
2e350 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2e360 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
2e370 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 pare16_v2()] ins
2e380 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c tead.** of the l
2e390 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 egacy [sqlite3_p
2e3a0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 repare()] and [s
2e3b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2e3c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a ()] interfaces,.
2e3d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 ** then the more
2e3e0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
2e3f0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 codes] are retu
2e400 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a rned directly.**
2e410 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
2e420 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 (). The use of
2e430 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2e440 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
2e450 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
2e460 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 3_step(sqlite3_s
2e470 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
2e480 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f PI3REF: Number o
2e490 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 f columns in a r
2e4a0 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 esult set.** MET
2e4b0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
2e4c0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c t.**.** ^The sql
2e4d0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
2e4e0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 P) interface ret
2e4f0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
2e500 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
2e510 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 e.** current row
2e520 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
2e530 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 et of [prepared
2e540 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a statement] P..**
2e550 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 ^If prepared st
2e560 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e atement P does n
2e570 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 ot have results
2e580 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a ready to return.
2e590 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f ** (via calls to
2e5a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
2e5b0 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 lumn_int | sqlit
2e5c0 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f e3_column_*()] o
2e5d0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 f.** interfaces)
2e5e0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 then sqlite3_da
2e5f0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 ta_count(P) retu
2e600 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 rns 0..** ^The s
2e610 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2e620 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 t(P) routine als
2e630 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 o returns 0 if P
2e640 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
2e650 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 er..** ^The sqli
2e660 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
2e670 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
2e680 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 s 0 if the previ
2e690 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ous call to.** [
2e6a0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 sqlite3_step](P)
2e6b0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
2e6c0 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 E_DONE]. ^The s
2e6d0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2e6e0 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 t(P).** will ret
2e6f0 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 urn non-zero if
2e700 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
2e710 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 [sqlite3_step](
2e720 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b P) returned.** [
2e730 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 SQLITE_ROW], exc
2e740 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 ept in the case
2e750 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 of the [PRAGMA i
2e760 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 ncremental_vacuu
2e770 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 m].** where it a
2e780 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 lways returns ze
2e790 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 ro since each st
2e7a0 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 ep of that multi
2e7b0 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 -step.** pragma
2e7c0 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e returns 0 column
2e7d0 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a s of data..**.**
2e7e0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
2e7f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 te3_column_count
2e800 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ()].*/.int sqlit
2e810 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 e3_data_count(sq
2e820 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
2e830 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2e840 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c REF: Fundamental
2e850 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 Datatypes.** KE
2e860 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 YWORDS: SQLITE_T
2e870 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 EXT.**.** ^(Ever
2e880 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 y value in SQLit
2e890 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 e has one of fiv
2e8a0 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 e fundamental da
2e8b0 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c tatypes:.**.** <
2e8c0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 ul>.** <li> 64-b
2e8d0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
2e8e0 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 r.** <li> 64-bit
2e8f0 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 IEEE floating p
2e900 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c oint number.** <
2e910 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c li> string.** <l
2e920 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 i> BLOB.** <li>
2e930 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a NULL.** </ul>)^.
2e940 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
2e950 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 tants are codes
2e960 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 for each of thos
2e970 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e e types..**.** N
2e980 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c ote that the SQL
2e990 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e ITE_TEXT constan
2e9a0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 t was also used
2e9b0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f in SQLite versio
2e9c0 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d n 2.** for a com
2e9d0 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e pletely differen
2e9e0 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 t meaning. Soft
2e9f0 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 ware that links
2ea00 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 against both.**
2ea10 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 SQLite version 2
2ea20 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 and SQLite vers
2ea30 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 ion 3 should use
2ea40 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e SQLITE3_TEXT, n
2ea50 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 ot.** SQLITE_TEX
2ea60 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 T..*/.#define SQ
2ea70 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a LITE_INTEGER 1.
2ea80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
2ea90 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e LOAT 2.#defin
2eaa0 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 e SQLITE_BLOB
2eab0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
2eac0 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 TE_NULL 5.#i
2ead0 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 fdef SQLITE_TEXT
2eae0 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
2eaf0 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 TEXT.#else.# def
2eb00 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 ine SQLITE_TEXT
2eb10 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 3.#endif.#de
2eb20 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 fine SQLITE3_TEX
2eb30 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 T 3../*.** C
2eb40 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 API3REF: Result
2eb50 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 Values From A Qu
2eb60 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ery.** KEYWORDS:
2eb70 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 {column access
2eb80 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 functions}.** ME
2eb90 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2eba0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 mt.**.** ^These
2ebb0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
2ebc0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 information abou
2ebd0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d t a single colum
2ebe0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 n of the current
2ebf0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f .** result row o
2ec00 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 f a query. ^In
2ec10 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 every case the f
2ec20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
2ec30 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
2ec40 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
2ec50 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 tatement] that i
2ec60 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 s being evaluate
2ec70 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f d (the [sqlite3_
2ec80 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 stmt*].** that w
2ec90 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d as returned from
2eca0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2ecb0 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f e_v2()] or one o
2ecc0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a f its variants).
2ecd0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e ** and the secon
2ece0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
2ecf0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 e index of the c
2ed00 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 olumn for which
2ed10 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 information.** s
2ed20 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
2ed30 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 d. ^The leftmost
2ed40 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
2ed50 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 esult set has th
2ed60 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 e index 0..** ^T
2ed70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
2ed80 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 umns in the resu
2ed90 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d lt can be determ
2eda0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 ined using.** [s
2edb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
2edc0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 unt()]..**.** If
2edd0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2ede0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 nt does not curr
2edf0 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 ently point to a
2ee00 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 valid row, or i
2ee10 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 f the.** column
2ee20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
2ee30 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c range, the resul
2ee40 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a t is undefined..
2ee50 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
2ee60 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 s may only be ca
2ee70 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f lled when the mo
2ee80 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
2ee90 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
2eea0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
2eeb0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
2eec0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b and neither.** [
2eed0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2eee0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 nor [sqlite3_fi
2eef0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 nalize()] have b
2ef00 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 een called subse
2ef10 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 quently..** If a
2ef20 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
2ef30 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
2ef40 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 after [sqlite3_r
2ef50 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
2ef60 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2ef70 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c )] or after [sql
2ef80 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
2ef90 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d returned.** som
2efa0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
2efb0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 n [SQLITE_ROW],
2efc0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
2efd0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 undefined..** If
2efe0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2eff0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
2f000 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
2f010 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a e3_finalize()].*
2f020 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f * are called fro
2f030 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 m a different th
2f040 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f read while any o
2f050 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
2f060 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c .** are pending,
2f070 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
2f080 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
2f090 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2f0a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
2f0b0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
2f0c0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 s the.** [SQLITE
2f0d0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 _INTEGER | datat
2f0e0 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 ype code] for th
2f0f0 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 e initial data t
2f100 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 ype.** of the re
2f110 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 sult column. ^T
2f120 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 he returned valu
2f130 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c e is one of [SQL
2f140 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a ITE_INTEGER],.**
2f150 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c [SQLITE_FLOAT],
2f160 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 [SQLITE_TEXT],
2f170 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f [SQLITE_BLOB], o
2f180 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e r [SQLITE_NULL].
2f190 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 The value.** r
2f1a0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
2f1b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
2f1c0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 is only meaning
2f1d0 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a ful if no type.*
2f1e0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 * conversions ha
2f1f0 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 ve occurred as d
2f200 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 escribed below.
2f210 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f After a type co
2f220 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 nversion,.** the
2f230 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
2f240 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
2f250 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 n_type() is unde
2f260 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a fined. Future.*
2f270 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 * versions of SQ
2f280 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 Lite may change
2f290 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
2f2a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2f2b0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 ype().** followi
2f2c0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 ng a type conver
2f2d0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 sion..**.** ^If
2f2e0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2f2f0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 BLOB or UTF-8 st
2f300 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 ring then the sq
2f310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2f320 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 es().** routine
2f330 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
2f340 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
2f350 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 hat BLOB or stri
2f360 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 ng..** ^If the r
2f370 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 esult is a UTF-1
2f380 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 6 string, then s
2f390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2f3a0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a tes() converts.*
2f3b0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 * the string to
2f3c0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 UTF-8 and then r
2f3d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
2f3e0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e r of bytes..** ^
2f3f0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
2f400 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 a numeric value
2f410 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
2f420 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 lumn_bytes() use
2f430 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e s.** [sqlite3_sn
2f440 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e printf()] to con
2f450 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 vert that value
2f460 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e to a UTF-8 strin
2f470 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
2f480 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2f490 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
2f4a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
2f4b0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
2f4c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2f4d0 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 umn_bytes() retu
2f4e0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 rns zero..**.**
2f4f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2f500 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
2f510 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 16 string then t
2f520 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
2f530 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 n_bytes16().** r
2f540 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
2f550 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
2f560 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 es in that BLOB
2f570 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 or string..** ^I
2f580 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
2f590 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 a UTF-8 string,
2f5a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2f5b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f umn_bytes16() co
2f5c0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 nverts.** the st
2f5d0 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 ring to UTF-16 a
2f5e0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 nd then returns
2f5f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
2f600 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 tes..** ^If the
2f610 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 result is a nume
2f620 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 ric value then s
2f630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2f640 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 tes16() uses.**
2f650 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
2f660 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 f()] to convert
2f670 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 that value to a
2f680 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e UTF-16 string an
2f690 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 d returns.** the
2f6a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2f6b0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e in that string.
2f6c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2f6d0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e lt is NULL, then
2f6e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2f6f0 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e bytes16() return
2f700 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 s zero..**.** ^T
2f710 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e he values return
2f720 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
2f730 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 olumn_bytes()] a
2f740 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nd .** [sqlite3_
2f750 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
2f760 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 ] do not include
2f770 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e the zero termin
2f780 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 ators at the end
2f790 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e .** of the strin
2f7a0 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 g. ^For clarity
2f7b0 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 : the values ret
2f7c0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
2f7d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2f7e0 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 s()] and [sqlite
2f7f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
2f800 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 ()] are the numb
2f810 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 er of.** bytes i
2f820 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f n the string, no
2f830 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
2f840 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a characters..**.*
2f850 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 * ^Strings retur
2f860 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
2f870 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 olumn_text() and
2f880 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2f890 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 text16(),.** eve
2f8a0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c n empty strings,
2f8b0 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f are always zero
2f8c0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 -terminated. ^T
2f8d0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c he return.** val
2f8e0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
2f8f0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f column_blob() fo
2f900 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 r a zero-length
2f910 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 BLOB is a NULL p
2f920 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 ointer..**.** <b
2f930 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 >Warning:</b> ^T
2f940 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e he object return
2f950 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
2f960 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
2f970 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 s an.** [unprote
2f980 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2f990 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 ue] object. In
2f9a0 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 a multithreaded
2f9b0 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 environment,.**
2f9c0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 an unprotected s
2f9d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2f9e0 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 ect may only be
2f9f0 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 used safely with
2fa00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2fa10 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b d_value()] and [
2fa20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
2fa30 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 alue()]..** If t
2fa40 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 he [unprotected
2fa50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
2fa60 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
2fa70 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
2fa80 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
2fa90 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 used in any oth
2faa0 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e er way, includin
2fab0 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f g calls.** to ro
2fac0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c utines like [sql
2fad0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 ite3_value_int()
2fae0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
2faf0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
2fb00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2fb10 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 bytes()], the be
2fb20 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 havior is not th
2fb30 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 readsafe..**.**
2fb40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
2fb50 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 ttempt to conver
2fb60 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 t the value wher
2fb70 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 e appropriate.
2fb80 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c ^For.** example,
2fb90 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c if the internal
2fba0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
2fbb0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 is FLOAT and a t
2fbc0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ext result.** is
2fbd0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c requested, [sql
2fbe0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
2fbf0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 is used interna
2fc00 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 lly to perform t
2fc10 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e he.** conversion
2fc20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
2fc30 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ^(The following
2fc40 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 table details t
2fc50 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a he conversions.*
2fc60 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 * that are appli
2fc70 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ed:.**.** <block
2fc80 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 quote>.** <table
2fc90 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 border="1">.**
2fca0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 <tr><th> Interna
2fcb0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 l<br>Type <th> R
2fcc0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 equested<br>Type
2fcd0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f <th> Conversio
2fce0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e n.**.** <tr><td>
2fcf0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 NULL <td> I
2fd00 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 NTEGER <td> Re
2fd10 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 sult is 0.** <tr
2fd20 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
2fd30 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
2fd40 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 d> Result is 0.0
2fd50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
2fd60 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 LL <td> TEX
2fd70 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 T <td> Result
2fd80 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
2fd90 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 er.** <tr><td>
2fda0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 NULL <td> B
2fdb0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 LOB <td> Resu
2fdc0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 lt is a NULL poi
2fdd0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e nter.** <tr><td>
2fde0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
2fdf0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f FLOAT <td> Co
2fe00 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 nvert from integ
2fe10 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c er to float.** <
2fe20 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
2fe30 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
2fe40 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 <td> ASCII rende
2fe50 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 ring of the inte
2fe60 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ger.** <tr><td>
2fe70 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 INTEGER <td>
2fe80 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d BLOB <td> Sam
2fe90 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 e as INTEGER->TE
2fea0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 XT.** <tr><td>
2feb0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 FLOAT <td> INT
2fec0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 EGER <td> [CAS
2fed0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a T] to INTEGER.**
2fee0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
2fef0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
2ff00 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e <td> ASCII ren
2ff10 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c dering of the fl
2ff20 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
2ff30 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
2ff40 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 BLOB <td> [CA
2ff50 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c ST] to BLOB.** <
2ff60 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 tr><td> TEXT
2ff70 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
2ff80 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 <td> [CAST] to I
2ff90 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 NTEGER.** <tr><t
2ffa0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
2ffb0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
2ffc0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a [CAST] to REAL.*
2ffd0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
2ffe0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
2fff0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 <td> No chang
30000 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 e.** <tr><td> B
30010 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 LOB <td> INTE
30020 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 GER <td> [CAST
30030 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 ] to INTEGER.**
30040 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
30050 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
30060 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 <td> [CAST] to
30070 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e REAL.** <tr><td>
30080 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 BLOB <td>
30090 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 TEXT <td> Ad
300a0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 d a zero termina
300b0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a tor if needed.**
300c0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 </table>.** </b
300d0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a lockquote>)^.**.
300e0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 ** Note that whe
300f0 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f n type conversio
30100 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 ns occur, pointe
30110 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 rs returned by p
30120 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f rior.** calls to
30130 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30140 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f blob(), sqlite3_
30150 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 column_text(), a
30160 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 nd/or.** sqlite3
30170 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
30180 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 may be invalida
30190 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e ted..** Type con
301a0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 versions and poi
301b0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f nter invalidatio
301c0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a ns might occur.*
301d0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 * in the followi
301e0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 ng cases:.**.**
301f0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 <ul>.** <li> The
30200 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
30210 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 is a BLOB and s
30220 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
30230 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 xt() or.**
30240 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
30250 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 ext16() is calle
30260 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 d. A zero-termi
30270 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 nator might.**
30280 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 need to be a
30290 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 dded to the stri
302a0 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e ng.</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 38 20 74 65 tent is UTF-8 te
302d0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 xt and sqlite3_c
302e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
302f0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
30300 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
30310 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
30320 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
30330 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
30340 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c to UTF-16.<
30350 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 /li>.** <li> The
30360 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
30370 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 is UTF-16 text
30380 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
30390 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a mn_bytes() or.**
303a0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
303b0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 lumn_text() is c
303c0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 alled. The cont
303d0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ent must be conv
303e0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f erted.** to
303f0 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 UTF-8.</li>.**
30400 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e </ul>.**.** ^Con
30410 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e versions between
30420 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 UTF-16be and UT
30430 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 F-16le are alway
30440 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 s done in place
30450 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e and do.** not in
30460 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 validate a prior
30470 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 pointer, though
30480 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 of course the c
30490 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 ontent of the bu
304a0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 ffer.** that the
304b0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 prior pointer r
304c0 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 eferences will h
304d0 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 ave been modifie
304e0 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a d. Other kinds.
304f0 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e ** of conversion
30500 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 are done in pla
30510 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f ce when it is po
30520 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 ssible, but some
30530 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 times they.** ar
30540 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 e not possible a
30550 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 nd in those case
30560 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 s prior pointers
30570 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 are invalidated
30580 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 ..**.** The safe
30590 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 st policy is to
305a0 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 invoke these rou
305b0 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 tines.** in one
305c0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
305d0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c ways:.**.** <ul
305e0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
305f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
30600 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
30610 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
30620 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e ()</li>.** <li>
30630 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
30640 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 lob() followed b
30650 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
30660 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
30670 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
30680 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f lumn_text16() fo
30690 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
306a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
306b0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e ()</li>.** </ul>
306c0 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 .**.** In other
306d0 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c words, you shoul
306e0 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 d call sqlite3_c
306f0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a olumn_text(),.**
30700 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30710 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 blob(), or sqlit
30720 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
30730 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 () first to forc
30740 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 e the result.**
30750 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 into the desired
30760 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e format, then in
30770 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c voke sqlite3_col
30780 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a umn_bytes() or.*
30790 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
307a0 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 _bytes16() to fi
307b0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 nd the size of t
307c0 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e he result. Do n
307d0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 ot mix calls.**
307e0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
307f0 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 n_text() or sqli
30800 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
30810 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a ) with calls to.
30820 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
30830 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 n_bytes16(), and
30840 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c do not mix call
30850 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
30860 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 umn_text16().**
30870 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 with calls to sq
30880 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
30890 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 es()..**.** ^The
308a0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
308b0 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 ed are valid unt
308c0 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 il a type conver
308d0 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a sion occurs as.*
308e0 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 * described abov
308f0 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c e, or until [sql
30900 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 ite3_step()] or
30910 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
30920 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
30930 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 _finalize()] is
30940 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 called. ^The me
30950 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 mory space used
30960 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a to hold strings.
30970 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 ** and BLOBs is
30980 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 freed automatica
30990 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 lly. Do <em>not
309a0 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 </em> pass the p
309b0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
309c0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
309d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 3_column_blob()]
309e0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d , [sqlite3_colum
309f0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 n_text()], etc.
30a00 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 into.** [sqlite3
30a10 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _free()]..**.**
30a20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c ^(If a memory al
30a30 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f location error o
30a40 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 ccurs during the
30a50 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 evaluation of a
30a60 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 ny.** of these r
30a70 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 outines, a defau
30a80 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 lt value is retu
30a90 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 rned. The defau
30aa0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 lt value.** is e
30ab0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 ither the intege
30ac0 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e r 0, the floatin
30ad0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 g point number 0
30ae0 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a .0, or a NULL.**
30af0 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 pointer. Subse
30b00 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
30b10 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
30b20 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a )] will return.*
30b30 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d * [SQLITE_NOMEM]
30b40 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 .)^.*/.const voi
30b50 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
30b60 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 n_blob(sqlite3_s
30b70 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
30b80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
30b90 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 umn_bytes(sqlite
30ba0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
30bb0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
30bc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 column_bytes16(s
30bd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
30be0 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 t iCol);.double
30bf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
30c00 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 ouble(sqlite3_st
30c10 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
30c20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
30c30 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 mn_int(sqlite3_s
30c40 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
30c50 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
30c60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
30c70 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t64(sqlite3_stmt
30c80 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f *, int iCol);.co
30c90 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 nst unsigned cha
30ca0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
30cb0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 n_text(sqlite3_s
30cc0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
30cd0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
30ce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
30cf0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
30d00 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
30d10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30d20 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d type(sqlite3_stm
30d30 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 t*, int iCol);.s
30d40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 qlite3_value *sq
30d50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
30d60 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ue(sqlite3_stmt*
30d70 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a , int iCol);../*
30d80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
30d90 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 stroy A Prepared
30da0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
30db0 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a t.** DESTRUCTOR:
30dc0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
30dd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
30de0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 _finalize() func
30df0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 tion is called t
30e00 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 o delete a [prep
30e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
30e20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 .** ^If the most
30e30 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 recent evaluati
30e40 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d on of the statem
30e50 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 ent encountered
30e60 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 no errors.** or
30e70 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 if the statement
30e80 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 is never been e
30e90 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 valuated, then s
30ea0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
30eb0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c ) returns.** SQL
30ec0 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 ITE_OK. ^If the
30ed0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 most recent eva
30ee0 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 luation of state
30ef0 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 ment S failed, t
30f00 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 hen.** sqlite3_f
30f10 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 inalize(S) retur
30f20 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 ns the appropria
30f30 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 te [error code]
30f40 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 or.** [extended
30f50 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a error code]..**.
30f60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
30f70 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 finalize(S) rout
30f80 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 ine can be calle
30f90 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 d at any point d
30fa0 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 uring.** the lif
30fb0 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 e cycle of [prep
30fc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
30fd0 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 S:.** before sta
30fe0 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 tement S is ever
30ff0 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 evaluated, afte
31000 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 r.** one or more
31010 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
31020 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 e3_reset()], or
31030 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a after any call.*
31040 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 * to [sqlite3_st
31050 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 ep()] regardless
31060 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
31070 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 ot the statement
31080 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 has.** complete
31090 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a d execution..**.
310a0 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c ** ^Invoking sql
310b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 ite3_finalize()
310c0 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 on a NULL pointe
310d0 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 r is a harmless
310e0 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 no-op..**.** The
310f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
31100 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 t finalize every
31110 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
31120 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 ment] in order t
31130 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 o avoid.** resou
31140 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 rce leaks. It i
31150 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 s a grievous err
31160 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 or for the appli
31170 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f cation to try to
31180 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 use.** a prepar
31190 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 ed statement aft
311a0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 er it has been f
311b0 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 inalized. Any u
311c0 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 se of a prepared
311d0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 .** statement af
311e0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 ter it has been
311f0 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 finalized can re
31200 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 sult in undefine
31210 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 d and.** undesir
31220 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 able behavior su
31230 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 ch as segfaults
31240 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 and heap corrupt
31250 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ion..*/.int sqli
31260 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c te3_finalize(sql
31270 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
31280 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
31290 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 EF: Reset A Prep
312a0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
312b0 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a bject.** METHOD:
312c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
312d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
312e0 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e reset() function
312f0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 is called to re
31300 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 set a [prepared
31310 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 statement].** ob
31320 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 ject back to its
31330 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 initial state,
31340 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 ready to be re-e
31350 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 xecuted..** ^Any
31360 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 SQL statement v
31370 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 ariables that ha
31380 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 d values bound t
31390 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 o them using.**
313a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
313b0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
313c0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 _bind_*() API] r
313d0 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 etain their valu
313e0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 es..** Use [sqli
313f0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
31400 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 gs()] to reset t
31410 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a he bindings..**.
31420 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
31430 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 _reset(S)] inter
31440 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 face resets the
31450 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
31460 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 ent] S.** back t
31470 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
31480 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a of its program..
31490 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
314a0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
314b0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
314c0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
314d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
314e0 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b nt] S returned [
314f0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b SQLITE_ROW] or [
31500 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a SQLITE_DONE],.**
31510 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f or if [sqlite3_
31520 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 step(S)] has nev
31530 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 er before been c
31540 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 alled on S,.** t
31550 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 hen [sqlite3_res
31560 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b et(S)] returns [
31570 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
31580 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 * ^If the most r
31590 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
315a0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
315b0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 for the.** [prep
315c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
315d0 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 S indicated an e
315e0 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 rror, then.** [s
315f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
31600 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 returns an appr
31610 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
31620 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode]..**.** ^The
31630 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
31640 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f S)] interface do
31650 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
31660 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 e values.** of a
31670 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ny [sqlite3_bind
31680 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 _blob|bindings]
31690 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 on the [prepared
316a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a statement] S..*
316b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 /.int sqlite3_re
316c0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 set(sqlite3_stmt
316d0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
316e0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 CAPI3REF: Creat
316f0 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 e Or Redefine SQ
31700 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b L Functions.** K
31710 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 EYWORDS: {functi
31720 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
31730 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 ines}.** KEYWORD
31740 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
31750 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
31760 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 tion}.** KEYWORD
31770 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
31780 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
31790 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 tions}.** METHOD
317a0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
317b0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
317c0 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b (collectively k
317d0 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f nown as "functio
317e0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 n creation routi
317f0 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 nes").** are use
31800 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e d to add SQL fun
31810 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
31820 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 ates or to redef
31830 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 ine the behavior
31840 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 .** of existing
31850 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 SQL functions or
31860 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 aggregates. Th
31870 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 e only differenc
31880 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 es between.** th
31890 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
318a0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 the text encodi
318b0 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a ng expected for.
318c0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 ** the second pa
318d0 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d rameter (the nam
318e0 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f e of the functio
318f0 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 n being created)
31900 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 .** and the pres
31910 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 ence or absence
31920 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 of a destructor
31930 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 callback for.**
31940 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
31950 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a data pointer..**
31960 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 .** ^The first p
31970 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
31980 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
31990 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 tion] to which t
319a0 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 he SQL.** functi
319b0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 on is to be adde
319c0 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 d. ^If an appli
319d0 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 cation uses more
319e0 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 than one databa
319f0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
31a00 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f then applicatio
31a10 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
31a20 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 nctions must be
31a30 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 added.** to each
31a40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
31a50 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e tion separately.
31a60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f .**.** ^The seco
31a70 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
31a80 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
31a90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
31aa0 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a be created or.**
31ab0 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 redefined. ^Th
31ac0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
31ad0 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 name is limited
31ae0 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 to 255 bytes in
31af0 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 a UTF-8.** repre
31b00 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 sentation, exclu
31b10 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f sive of the zero
31b20 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e -terminator. ^N
31b30 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d ote that the nam
31b40 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 e.** length limi
31b50 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 t is in UTF-8 by
31b60 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 tes, not charact
31b70 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 ers nor UTF-16 b
31b80 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 ytes. .** ^Any
31b90 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 attempt to creat
31ba0 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 e a function wit
31bb0 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a h a longer name.
31bc0 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 ** will result i
31bd0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 n [SQLITE_MISUSE
31be0 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 ] being returned
31bf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 ..**.** ^The thi
31c00 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 rd parameter (nA
31c10 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 rg).** is the nu
31c20 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
31c30 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 s that the SQL f
31c40 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
31c50 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e gregate takes. ^
31c60 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 If this paramete
31c70 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 r is -1, then th
31c80 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
31c90 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d r.** aggregate m
31ca0 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 ay take any numb
31cb0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
31cc0 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 between 0 and th
31cd0 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 e limit.** set b
31ce0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 y [sqlite3_limit
31cf0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ]([SQLITE_LIMIT_
31d00 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 FUNCTION_ARG]).
31d10 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a If the third.**
31d20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 parameter is le
31d30 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 ss than -1 or gr
31d40 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 eater than 127 t
31d50 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
31d60 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 is.** undefined
31d70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
31d80 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 rth parameter, e
31d90 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 TextRep, specifi
31da0 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 es what.** [SQLI
31db0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 TE_UTF8 | text e
31dc0 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 ncoding] this SQ
31dd0 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 L function prefe
31de0 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 rs for.** its pa
31df0 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 rameters. The a
31e00 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
31e10 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d d set this param
31e20 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 eter to.** [SQLI
31e30 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 TE_UTF16LE] if t
31e40 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c he function impl
31e50 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b ementation invok
31e60 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f es .** [sqlite3_
31e70 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 value_text16le()
31e80 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f ] on an input, o
31e90 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 r [SQLITE_UTF16B
31ea0 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 E] if the.** imp
31eb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f lementation invo
31ec0 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c kes [sqlite3_val
31ed0 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f ue_text16be()] o
31ee0 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a n an input, or.*
31ef0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d * [SQLITE_UTF16]
31f00 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c if [sqlite3_val
31f10 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 ue_text16()] is
31f20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 used, or [SQLITE
31f30 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 _UTF8].** otherw
31f40 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 ise. ^The same
31f50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 SQL function may
31f60 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d be registered m
31f70 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 ultiple times us
31f80 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 ing.** different
31f90 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
31fa0 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 encodings, with
31fb0 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d different implem
31fc0 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a entations for.**
31fd0 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a each encoding..
31fe0 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c ** ^When multipl
31ff0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
32000 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
32010 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c nction are avail
32020 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 able, SQLite.**
32030 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e will pick the on
32040 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 e that involves
32050 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 the least amount
32060 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 of data convers
32070 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ion..**.** ^The
32080 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
32090 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 may optionally
320a0 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 be ORed with [SQ
320b0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 LITE_DETERMINIST
320c0 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c IC].** to signal
320d0 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 that the functi
320e0 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 on will always r
320f0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 eturn the same r
32100 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 esult given.** t
32110 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 he same inputs w
32120 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 ithin a single S
32130 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d QL statement. M
32140 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ost SQL function
32150 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 s are.** determi
32160 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 nistic. The bui
32170 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d lt-in [random()]
32180 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 SQL function is
32190 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 an example of a
321a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 .** function tha
321b0 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 t is not determi
321c0 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c nistic. The SQL
321d0 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 ite query planne
321e0 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 r is able to.**
321f0 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e perform addition
32200 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 al optimizations
32210 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 on deterministi
32220 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 c functions, so
32230 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 use.** of the [S
32240 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 QLITE_DETERMINIS
32250 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 TIC] flag is rec
32260 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 ommended where p
32270 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e ossible..**.** ^
32280 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d (The fifth param
32290 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 eter is an arbit
322a0 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 rary pointer. T
322b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
322c0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 n of the.** func
322d0 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 tion can gain ac
322e0 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 cess to this poi
322f0 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 nter using [sqli
32300 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d te3_user_data()]
32310 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
32320 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e ixth, seventh an
32330 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 d eighth paramet
32340 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 ers, xFunc, xSte
32350 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 p and xFinal, ar
32360 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f e.** pointers to
32370 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 C-language func
32380 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 tions that imple
32390 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e ment the SQL fun
323a0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
323b0 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 egate. ^A scalar
323c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 SQL function re
323d0 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d quires an implem
323e0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 entation of the
323f0 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 xFunc.** callbac
32400 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 k only; NULL poi
32410 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 nters must be pa
32420 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 ssed as the xSte
32430 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 p and xFinal.**
32440 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 parameters. ^An
32450 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
32460 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
32470 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f an implementatio
32480 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e n of xStep.** an
32490 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c d xFinal and NUL
324a0 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 L pointer must b
324b0 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 e passed for xFu
324c0 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 nc. ^To delete a
324d0 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 n existing.** SQ
324e0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 L function or ag
324f0 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 gregate, pass NU
32500 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 LL pointers for
32510 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 all three functi
32520 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e on.** callbacks.
32530 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 .**.** ^(If the
32540 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 ninth parameter
32550 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 to sqlite3_creat
32560 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 e_function_v2()
32570 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 is not NULL,.**
32580 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 then it is destr
32590 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 uctor for the ap
325a0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 plication data p
325b0 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 ointer. .** The
325c0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e destructor is in
325d0 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 voked when the f
325e0 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 unction is delet
325f0 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 ed, either by be
32600 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 ing.** overloade
32610 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 d or when the da
32620 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
32630 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e n closes.)^.** ^
32640 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
32650 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 s also invoked i
32660 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a f the call to.**
32670 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
32680 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 function_v2() fa
32690 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 ils..** ^When th
326a0 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c e destructor cal
326b0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e lback of the ten
326c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
326d0 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 invoked, it.** i
326e0 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c s passed a singl
326f0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
32700 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
32710 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 e application da
32720 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 ta .** pointer w
32730 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 hich was the fif
32740 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
32750 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
32760 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a unction_v2()..**
32770 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 .** ^It is permi
32780 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 tted to register
32790 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d multiple implem
327a0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 entations of the
327b0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f same.** functio
327c0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 ns with the same
327d0 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 name but with e
327e0 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 ither differing
327f0 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 numbers of.** ar
32800 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 guments or diffe
32810 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 ring preferred t
32820 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 ext encodings.
32830 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 ^SQLite will use
32840 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
32850 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 tation that most
32860 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 closely matches
32870 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 the way in whic
32880 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e h the.** SQL fun
32890 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 ction is used.
328a0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c ^A function impl
328b0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 ementation with
328c0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a a non-negative.*
328d0 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 * nArg parameter
328e0 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 is a better mat
328f0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 ch than a functi
32900 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
32910 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 n with.** a nega
32920 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 tive nArg. ^A f
32930 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
32940 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 e preferred text
32950 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 encoding.** mat
32960 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 ches the databas
32970 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 e encoding is a
32980 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 better.** match
32990 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
329a0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
329b0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e ng is different.
329c0 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f .** ^A functio
329d0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
329e0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 ding difference
329f0 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 is between UTF16
32a00 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a le and UTF16be.*
32a10 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 * is a closer ma
32a20 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 tch than a funct
32a30 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e ion where the en
32a40 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 coding differenc
32a50 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 e is.** between
32a60 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a UTF8 and UTF16..
32a70 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 **.** ^Built-in
32a80 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 functions may be
32a90 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e overloaded by n
32aa0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 ew application-d
32ab0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 efined functions
32ac0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c ..**.** ^An appl
32ad0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
32ae0 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d function is perm
32af0 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 itted to call ot
32b00 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e her.** SQLite in
32b10 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 terfaces. Howev
32b20 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d er, such calls m
32b30 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 ust not.** close
32b40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
32b50 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e nnection nor fin
32b60 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 alize or reset t
32b70 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 he prepared.** s
32b80 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 tatement in whic
32b90 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 h the function i
32ba0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e s running..*/.in
32bb0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
32bc0 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c _function(. sql
32bd0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
32be0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
32bf0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
32c00 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
32c10 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
32c20 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
32c30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
32c40 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
32c50 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
32c60 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
32c70 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
32c80 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
32c90 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
32ca0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
32cb0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
32cc0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
32cd0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 16(. sqlite3 *d
32ce0 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 b,. const void
32cf0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
32d00 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
32d10 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
32d20 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
32d30 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
32d40 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
32d50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
32d60 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
32d70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
32d80 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
32d90 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
32da0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
32db0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e _context*).);.in
32dc0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
32dd0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 _function_v2(.
32de0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
32df0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
32e00 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
32e10 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
32e20 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
32e30 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
32e40 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
32e50 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
32e60 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
32e70 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
32e80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
32e90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
32ea0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
32eb0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
32ec0 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 xt*),. void(*xD
32ed0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 estroy)(void*).)
32ee0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
32ef0 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 F: Text Encoding
32f00 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f s.**.** These co
32f10 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e nstant define in
32f20 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 teger codes that
32f30 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 represent the v
32f40 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 arious.** text e
32f50 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 ncodings support
32f60 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f ed by SQLite..*/
32f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
32f80 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 UTF8 1
32f90 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 /* IMP: R-37
32fa0 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 514-35566 */.#de
32fb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
32fc0 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20 6LE 2
32fd0 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d /* IMP: R-03371-
32fe0 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 37637 */.#define
32ff0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 SQLITE_UTF16BE
33000 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 3 /* I
33010 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 MP: R-51971-3415
33020 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 4 */.#define SQL
33030 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 ITE_UTF16
33040 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 4 /* Use n
33050 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
33060 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
33070 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 TE_ANY
33080 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 5 /* Deprec
33090 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ated */.#define
330a0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
330b0 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 GNED 8 /* sq
330c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
330d0 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a lation only */..
330e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
330f0 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a Function Flags.*
33100 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
33110 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 ants may be ORed
33120 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 together with t
33130 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 he .** [SQLITE_U
33140 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 TF8 | preferred
33150 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 text encoding] a
33160 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 s the fourth arg
33170 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c ument.** to [sql
33180 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
33190 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 tion()], [sqlite
331a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
331b0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 n16()], or.** [s
331c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
331d0 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f nction_v2()]..*/
331e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
331f0 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 DETERMINISTIC
33200 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 0x800../*.** CA
33210 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 PI3REF: Deprecat
33220 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 ed Functions.**
33230 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a DEPRECATED.**.**
33240 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
33250 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 are [deprecated
33260 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 ]. In order to
33270 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b maintain.** back
33280 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
33290 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 ity with older c
332a0 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 ode, these funct
332b0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a ions continue .*
332c0 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 * to be supporte
332d0 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 d. However, new
332e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 applications sh
332f0 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 ould avoid.** th
33300 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 e use of these f
33310 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e unctions. To en
33320 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d courage programm
33330 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 ers to avoid.**
33340 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c these functions,
33350 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 we will not exp
33360 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 lain what they d
33370 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 o..*/.#ifndef SQ
33380 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 LITE_OMIT_DEPREC
33390 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 ATED.SQLITE_DEPR
333a0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
333b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 e3_aggregate_cou
333c0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 nt(sqlite3_conte
333d0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 xt*);.SQLITE_DEP
333e0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
333f0 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 te3_expired(sqli
33400 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
33410 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
33420 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 t sqlite3_transf
33430 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 er_bindings(sqli
33440 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 te3_stmt*, sqlit
33450 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 e3_stmt*);.SQLIT
33460 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
33470 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f sqlite3_global_
33480 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 recover(void);.S
33490 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
334a0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 void sqlite3_th
334b0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 read_cleanup(voi
334c0 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 d);.SQLITE_DEPRE
334d0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
334e0 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 3_memory_alarm(v
334f0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
33500 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c ite3_int64,int),
33510 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
33520 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c void*,sql
33530 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e ite3_int64);.#en
33540 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
33550 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 REF: Obtaining S
33560 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 QL Values.** MET
33570 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c HOD: sqlite3_val
33580 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c ue.**.** The C-l
33590 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e anguage implemen
335a0 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 tation of SQL fu
335b0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
335c0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 egates uses.** t
335d0 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 his set of inter
335e0 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f face routines to
335f0 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 access the para
33600 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a meter values on.
33610 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 ** the function
33620 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a or aggregate. .
33630 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 **.** The xFunc
33640 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 (for scalar func
33650 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 tions) or xStep
33660 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 (for aggregates)
33670 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 parameters.** t
33680 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
33690 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
336a0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
336b0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
336c0 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 ** define callba
336d0 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 cks that impleme
336e0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
336f0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
33700 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 tes..** The 3rd
33710 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
33720 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 se callbacks is
33730 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
33740 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 ters to.** [prot
33750 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
33760 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 lue] objects. T
33770 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c here is one [sql
33780 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
33790 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 ct for.** each p
337a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
337b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 SQL function. T
337c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
337d0 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 e used to.** ext
337e0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d ract values from
337f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
33800 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a lue] objects..**
33810 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
33820 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 es work only wit
33830 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c h [protected sql
33840 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
33850 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 cts..** Any atte
33860 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 mpt to use these
33870 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 routines on an
33880 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
33890 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f ite3_value].** o
338a0 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e bject results in
338b0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
338c0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ior..**.** ^Thes
338d0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
338e0 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f just like the co
338f0 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c rresponding [col
33900 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
33910 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 ions].** except
33920 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 that these routi
33930 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c nes take a singl
33940 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c e [protected sql
33950 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
33960 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e ct.** pointer in
33970 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 stead of a [sqli
33980 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 te3_stmt*] point
33990 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 er and an intege
339a0 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e r column number.
339b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
339c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
339d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 () interface ext
339e0 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 racts a UTF-16 s
339f0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 tring.** in the
33a00 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 native byte-orde
33a10 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 r of the host ma
33a20 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 chine. ^The.**
33a30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
33a40 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c xt16be() and sql
33a50 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
33a60 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 6le() interfaces
33a70 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d .** extract UTF-
33a80 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 16 strings as bi
33a90 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 g-endian and lit
33aa0 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 tle-endian respe
33ab0 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e ctively..**.** ^
33ac0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c (The sqlite3_val
33ad0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 ue_numeric_type(
33ae0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 ) interface atte
33af0 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a mpts to apply.**
33b00 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 numeric affinit
33b10 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 y to the value.
33b20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 This means that
33b30 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a an attempt is.*
33b40 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 * made to conver
33b50 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 t the value to a
33b60 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f n integer or flo
33b70 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 ating point. If
33b80 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 .** such a conve
33b90 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c rsion is possibl
33ba0 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f e without loss o
33bb0 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 f information (i
33bc0 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 n other.** words
33bd0 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 , if the value i
33be0 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 s a string that
33bf0 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d looks like a num
33c00 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ber).** then the
33c10 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 conversion is p
33c20 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 erformed. Other
33c30 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 wise no conversi
33c40 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 on occurs..** Th
33c50 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 e [SQLITE_INTEGE
33c60 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 R | datatype] af
33c70 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 ter conversion i
33c80 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a s returned.)^.**
33c90 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 .** Please pay p
33ca0 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 articular attent
33cb0 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 ion to the fact
33cc0 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 that the pointer
33cd0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f returned.** fro
33ce0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 m [sqlite3_value
33cf0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 _blob()], [sqlit
33d00 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d e3_value_text()]
33d10 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
33d20 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d _value_text16()]
33d30 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 can be invalida
33d40 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 ted by a subsequ
33d50 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ent call to.** [
33d60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
33d70 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 tes()], [sqlite3
33d80 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 _value_bytes16()
33d90 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
33da0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
33db0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
33dc0 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a text16()]..**.**
33dd0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
33de0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
33df0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
33e00 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 ead as.** the SQ
33e10 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 L function that
33e20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 supplied the [sq
33e30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 lite3_value*] pa
33e40 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e rameters..*/.con
33e50 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
33e60 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 _value_blob(sqli
33e70 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
33e80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 sqlite3_value_b
33e90 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c ytes(sqlite3_val
33ea0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ue*);.int sqlite
33eb0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 3_value_bytes16(
33ec0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
33ed0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f .double sqlite3_
33ee0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c value_double(sql
33ef0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e ite3_value*);.in
33f00 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
33f10 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 int(sqlite3_valu
33f20 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 e*);.sqlite3_int
33f30 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 64 sqlite3_value
33f40 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 _int64(sqlite3_v
33f50 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e alue*);.const un
33f60 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c signed char *sql
33f70 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
33f80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
33f90 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
33fa0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
33fb0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 6(sqlite3_value*
33fc0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
33fd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
33fe0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 t16le(sqlite3_va
33ff0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 lue*);.const voi
34000 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
34010 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 _text16be(sqlite
34020 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 3_value*);.int s
34030 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 qlite3_value_typ
34040 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
34050 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 );.int sqlite3_v
34060 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 alue_numeric_typ
34070 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
34080 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
34090 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 EF: Obtaining SQ
340a0 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 L Values.** METH
340b0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 OD: sqlite3_valu
340c0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 e.**.** The sqli
340d0 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 te3_value_subtyp
340e0 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 e(V) function re
340f0 74 75 72 6e 73 20 74 68 65 20 73 75 62 74 79 70 turns the subtyp
34100 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 61 70 70 6c e for.** an appl
34110 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
34120 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 SQL function arg
34130 75 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75 ument V. The su
34140 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 btype.** informa
34150 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 tion can be used
34160 20 74 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74 to pass a limit
34170 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e ed amount of con
34180 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 text from.** one
34190 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f SQL function to
341a0 20 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74 another. Use t
341b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 he [sqlite3_resu
341c0 6c 74 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a lt_subtype()].**
341d0 20 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20 routine to set
341e0 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 20 the subtype for
341f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
34200 20 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 of an SQL funct
34210 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ion..**.** SQLit
34220 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f e makes no use o
34230 66 20 73 75 62 74 79 70 65 20 69 74 73 65 6c 66 f subtype itself
34240 2e 20 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73 . It merely pas
34250 73 65 73 20 74 68 65 20 73 75 62 74 79 70 65 0a ses the subtype.
34260 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75 ** from the resu
34270 6c 74 20 6f 66 20 6f 6e 65 20 61 70 70 6c 69 63 lt of one applic
34280 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
34290 6e 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 69 6e nction to the in
342a0 70 75 74 20 6f 66 0a 2a 2a 20 61 6e 6f 74 68 65 put of.** anothe
342b0 72 2e 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64 20 69 r..*/.unsigned i
342c0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
342d0 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74 65 33 _subtype(sqlite3
342e0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _value*);../*.**
342f0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20 CAPI3REF: Copy
34300 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c And Free SQL Val
34310 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ues.** METHOD: s
34320 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a qlite3_value.**.
34330 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
34340 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 value_dup(V) int
34350 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 erface makes a c
34360 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 opy of the [sqli
34370 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 te3_value].** ob
34380 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74 75 72 ject D and retur
34390 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
343a0 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 that copy. ^The
343b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
343c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 returned.** is
343d0 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c a [protected sql
343e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
343f0 63 74 20 65 76 65 6e 20 69 66 20 74 68 65 20 69 ct even if the i
34400 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 nput is not..**
34410 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
34420 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 ue_dup(V) interf
34430 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c ace returns NULL
34440 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 if V is NULL or
34450 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 if a.** memory
34460 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 allocation fails
34470 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
34480 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 ite3_value_free(
34490 56 29 20 69 6e 74 65 72 66 61 63 65 20 66 72 65 V) interface fre
344a0 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 es an [sqlite3_v
344b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 alue] object.**
344c0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
344d0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
344e0 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 3_value_dup()].
344f0 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c ^If V is a NULL
34500 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e pointer.** then
34510 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 sqlite3_value_f
34520 72 65 65 28 56 29 20 69 73 20 61 20 68 61 72 6d ree(V) is a harm
34530 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 less no-op..*/.S
34540 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
34550 41 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 AL sqlite3_value
34560 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
34570 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69 74 65 dup(const sqlite
34580 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
34590 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 E_EXPERIMENTAL v
345a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 oid sqlite3_valu
345b0 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 e_free(sqlite3_v
345c0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 alue*);../*.** C
345d0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 API3REF: Obtain
345e0 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 Aggregate Functi
345f0 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 on Context.** ME
34600 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f THOD: sqlite3_co
34610 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c ntext.**.** Impl
34620 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 ementations of a
34630 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e ggregate SQL fun
34640 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a ctions use this.
34650 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c ** routine to al
34660 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f locate memory fo
34670 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 r storing their
34680 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 state..**.** ^Th
34690 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 e first time the
346a0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
346b0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 te_context(C,N)
346c0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 routine is calle
346d0 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 d .** for a part
346e0 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 icular aggregate
346f0 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 function, SQLit
34700 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e e.** allocates N
34710 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f of memory, zero
34720 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f es out that memo
34730 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ry, and returns
34740 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
34750 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 the new memory.
34760 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 ^On second and s
34770 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
34780 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 to.** sqlite3_ag
34790 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
347a0 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 ) for the same a
347b0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f ggregate functio
347c0 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 n instance,.** t
347d0 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 he same buffer i
347e0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c s returned. 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 69 73 20 6e 6f 72 6d ontext() is norm
34810 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f ally.** called o
34820 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 nce for each inv
34830 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 ocation of the x
34840 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e Step callback an
34850 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 d then one.** la
34860 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 st time when the
34870 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b xFinal callback
34880 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 is invoked. ^(
34890 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 When no rows mat
348a0 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 ch.** an aggrega
348b0 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 te query, the xS
348c0 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f tep() callback o
348d0 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 f the aggregate
348e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c function.** impl
348f0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 ementation is ne
34900 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 ver called and x
34910 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 Final() is calle
34920 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a d exactly once..
34930 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 ** In those case
34940 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 s, sqlite3_aggre
34950 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d gate_context() m
34960 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 ight be called f
34970 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 or the.** first
34980 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e time from within
34990 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a xFinal().)^.**.
349a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
349b0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
349c0 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 t(C,N) routine r
349d0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
349e0 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 inter .** when f
349f0 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e irst called if N
34a00 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 is less than or
34a10 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f equal to zero o
34a20 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a r if a memory.**
34a30 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 allocate error
34a40 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 occurs..**.** ^(
34a50 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 The amount of sp
34a60 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 ace allocated by
34a70 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
34a80 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 te_context(C,N)
34a90 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 is.** determined
34aa0 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 by the N parame
34ab0 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 ter on first suc
34ac0 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 cessful call. C
34ad0 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 hanging the.** v
34ae0 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 alue of N in sub
34af0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 sequent call to
34b00 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
34b10 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 e_context() with
34b20 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 in.** the same a
34b30 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f ggregate functio
34b40 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 n instance will
34b50 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d not resize the m
34b60 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
34b70 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 ion.)^ Within t
34b80 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 he xFinal callba
34b90 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d ck, it is custom
34ba0 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d ary to set.** N=
34bb0 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 0 in calls to sq
34bc0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
34bd0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 context(C,N) so
34be0 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e that no .** poin
34bf0 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c tless memory all
34c00 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a ocations occur..
34c10 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 **.** ^SQLite au
34c20 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 tomatically free
34c30 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c s the memory all
34c40 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 ocated by .** sq
34c50 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
34c60 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 context() when t
34c70 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 he aggregate que
34c80 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a ry concludes..**
34c90 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 .** The first pa
34ca0 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 rameter must be
34cb0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a a copy of the.**
34cc0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
34cd0 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e t | SQL function
34ce0 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 context] that i
34cf0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 s the first para
34d00 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 meter.** to the
34d10 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 xStep or xFinal
34d20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 callback routine
34d30 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 that implements
34d40 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a the aggregate.*
34d50 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a * function..**.*
34d60 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d * This routine m
34d70 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
34d80 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
34d90 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 ad in which.** t
34da0 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c he aggregate SQL
34db0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
34dc0 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 ning..*/.void *s
34dd0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
34de0 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 _context(sqlite3
34df0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e _context*, int n
34e00 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 Bytes);../*.** C
34e10 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 API3REF: User Da
34e20 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 ta For Functions
34e30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
34e40 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a te3_context.**.*
34e50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 * ^The sqlite3_u
34e60 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 ser_data() inter
34e70 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 face returns a c
34e80 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f opy of.** the po
34e90 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 inter that was t
34ea0 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 he pUserData par
34eb0 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 ameter (the 5th
34ec0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 parameter).** of
34ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
34ee0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
34ef0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
34f00 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
34f10 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 16()] routines t
34f20 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a hat originally.*
34f30 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 * registered the
34f40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 application def
34f50 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a ined function..*
34f60 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
34f70 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 e must be called
34f80 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
34f90 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a hread in which.*
34fa0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f * the applicatio
34fb0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
34fc0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
34fd0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
34fe0 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 user_data(sqlite
34ff0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 3_context*);../*
35000 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 .** CAPI3REF: Da
35010 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
35020 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a n For Functions.
35030 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
35040 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a e3_context.**.**
35050 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f ^The sqlite3_co
35060 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
35070 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
35080 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a rns a copy of.**
35090 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 the pointer to
350a0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
350b0 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 nnection] (the 1
350c0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a st parameter).**
350d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
350e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
350f0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
35100 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
35110 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 ion16()] routine
35120 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c s that originall
35130 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 y.** registered
35140 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
35150 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
35160 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 ..*/.sqlite3 *sq
35170 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
35180 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f _handle(sqlite3_
35190 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a context*);../*.*
351a0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 * CAPI3REF: Func
351b0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 tion Auxiliary D
351c0 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ata.** METHOD: s
351d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a qlite3_context.*
351e0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
351f0 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 ions may be used
35200 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 by (non-aggrega
35210 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e te) SQL function
35220 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 s to.** associat
35230 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 e metadata with
35240 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e argument values.
35250 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c If the same val
35260 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a ue is passed to.
35270 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f ** multiple invo
35280 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
35290 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ame SQL function
352a0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 during query ex
352b0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a ecution, under.*
352c0 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 * some circumsta
352d0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 nces the associa
352e0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 ted metadata may
352f0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 be preserved.
35300 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 An example.** of
35310 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 where this migh
35320 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 t be useful is i
35330 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 n a regular-expr
35340 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a ession matching.
35350 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 ** function. The
35360 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f compiled versio
35370 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 n of the regular
35380 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 expression can
35390 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 be stored as.**
353a0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 metadata associa
353b0 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74 ted with the pat
353c0 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a tern string. .*
353d0 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 * Then as long a
353e0 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 s the pattern st
353f0 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 ring remains the
35400 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f same,.** the co
35410 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 mpiled regular e
35420 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 xpression can be
35430 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 reused on multi
35440 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f ple.** invocatio
35450 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 ns of the same f
35460 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e unction..**.** ^
35470 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
35480 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 auxdata() interf
35490 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
354a0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 inter to the met
354b0 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 adata.** associa
354c0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 ted by the sqlit
354d0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
354e0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 function with t
354f0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a he Nth argument.
35500 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 ** value to the
35510 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
35520 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 ned function. ^I
35530 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 f there is no me
35540 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 tadata.** associ
35550 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75 ated with the fu
35560 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c nction argument,
35570 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 this sqlite3_ge
35580 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 t_auxdata() inte
35590 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 rface.** returns
355a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
355b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
355c0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
355d0 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 C,N,P,X) interfa
355e0 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 ce saves P as me
355f0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e tadata for the N
35600 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 -th.** argument
35610 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
35620 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
35630 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e ion. ^Subsequen
35640 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 t.** calls to sq
35650 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
35660 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 a(C,N) return P
35670 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 from the most re
35680 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cent.** 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 63 61 6c 6c 20 69 66 20 74 68 65 P,X) call if the
356b0 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69 metadata is sti
356c0 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e ll valid or.** N
356d0 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 ULL if the metad
356e0 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 ata has been dis
356f0 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 carded..** ^Afte
35700 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 r each call to s
35710 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
35720 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 ta(C,N,P,X) wher
35730 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c e X is not NULL,
35740 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 .** SQLite will
35750 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 invoke the destr
35760 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 uctor function X
35770 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 with parameter
35780 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 P exactly.** onc
35790 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 e, when the meta
357a0 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65 data is discarde
357b0 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 d..** SQLite is
357c0 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 free to discard
357d0 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 the metadata at
357e0 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 any time, includ
357f0 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 ing: <ul>.** <li
35800 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 > when the corre
35810 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f sponding functio
35820 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e n parameter chan
35830 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 ges, or.** <li>
35840 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 when [sqlite3_re
35850 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
35860 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 e3_finalize()] i
35870 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 s called for the
35880 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 .** SQL sta
35890 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c tement, or.** <l
358a0 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f i> when sqlite3_
358b0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 set_auxdata() is
358c0 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f invoked again o
358d0 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d n the same param
358e0 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e eter, or.** <li>
358f0 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 during the orig
35900 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 inal sqlite3_set
35910 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 _auxdata() call
35920 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a when a memory .*
35930 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f * allocatio
35940 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 n error occurs.
35950 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f </ul>)^.**.** No
35960 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c te the last bull
35970 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 et in particular
35980 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f . The destructo
35990 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 r X in .** sqlit
359a0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 e3_set_auxdata(C
359b0 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65 ,N,P,X) might be
359c0 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 called immediat
359d0 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a ely, before the.
359e0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 ** sqlite3_set_a
359f0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
35a00 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e ce even returns.
35a10 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f Hence sqlite3_
35a20 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a set_auxdata().**
35a30 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 should be calle
35a40 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f d near the end o
35a50 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 f the function i
35a60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e mplementation an
35a70 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f d the.** functio
35a80 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
35a90 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 should not make
35aa0 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66 any use of P af
35ab0 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 ter.** sqlite3_s
35ac0 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73 et_auxdata() has
35ad0 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a been called..**
35ae0 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 .** ^(In practic
35af0 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 e, metadata is p
35b00 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e reserved between
35b10 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 function calls
35b20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 for.** function
35b30 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 parameters that
35b40 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 are compile-time
35b50 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c constants, incl
35b60 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a uding literal.**
35b70 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 values and [par
35b80 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70 ameters] and exp
35b90 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 ressions compose
35ba0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e d from the same.
35bb0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 )^.**.** These r
35bc0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
35bd0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
35be0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
35bf0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 hich.** the SQL
35c00 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
35c10 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ing..*/.void *sq
35c20 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
35c30 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
35c40 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 t*, int N);.void
35c50 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
35c60 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e data(sqlite3_con
35c70 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f text*, int N, vo
35c80 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f id*, void (*)(vo
35c90 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 id*));.../*.** C
35ca0 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e API3REF: Constan
35cb0 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 ts Defining Spec
35cc0 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 ial Destructor B
35cd0 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 ehavior.**.** Th
35ce0 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 ese are special
35cf0 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 values for the d
35d00 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 estructor that i
35d10 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 s passed in as t
35d20 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 he.** final argu
35d30 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 ment to routines
35d40 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 like [sqlite3_r
35d50 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 esult_blob()].
35d60 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 ^If the destruct
35d70 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 or.** argument i
35d80 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c s SQLITE_STATIC,
35d90 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 it means that t
35da0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 he content point
35db0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a er is constant.*
35dc0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 * and will never
35dd0 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 change. It doe
35de0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 s not need to be
35df0 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 destroyed. ^Th
35e00 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e e.** SQLITE_TRAN
35e10 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e SIENT value mean
35e20 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 s that the conte
35e30 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 nt will likely c
35e40 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 hange in.** the
35e50 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 near future and
35e60 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 that SQLite shou
35e70 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 ld make its own
35e80 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a private copy of.
35e90 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 ** the content b
35ea0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e efore returning.
35eb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 .**.** The typed
35ec0 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 ef is necessary
35ed0 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 to work around p
35ee0 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 roblems in certa
35ef0 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c in.** C++ compil
35f00 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ers..*/.typedef
35f10 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 void (*sqlite3_d
35f20 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 estructor_type)(
35f30 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 void*);.#define
35f40 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 SQLITE_STATIC
35f50 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 ((sqlite3_des
35f60 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a tructor_type)0).
35f70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
35f80 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c RANSIENT ((sql
35f90 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f ite3_destructor_
35fa0 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 type)-1)../*.**
35fb0 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e CAPI3REF: Settin
35fc0 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 g The Result Of
35fd0 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a An SQL Function.
35fe0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
35ff0 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a e3_context.**.**
36000 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
36010 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 are used by the
36020 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 xFunc or xFinal
36030 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a callbacks that.*
36040 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 * implement SQL
36050 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
36060 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a gregates. See.*
36070 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
36080 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
36090 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
360a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
360b0 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 ** for additiona
360c0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
360d0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
360e0 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d ions work very m
360f0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 uch like the [pa
36100 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d rameter binding]
36110 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 family of.** fu
36120 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 nctions used to
36130 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 bind values to h
36140 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 ost parameters i
36150 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 n prepared state
36160 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 ments..** Refer
36170 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 to the [SQL para
36180 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 meter] documenta
36190 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f tion for additio
361a0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
361b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
361c0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
361d0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
361e0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
361f0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 .** an applicati
36200 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
36210 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c ion to be the BL
36220 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 OB whose content
36230 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 is pointed.** t
36240 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 o by the second
36250 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 parameter and wh
36260 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c ich is N bytes l
36270 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 ong where N is t
36280 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 he.** third para
36290 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 meter..**.** ^Th
362a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
362b0 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 20 61 _zeroblob(C,N) a
362c0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c nd sqlite3_resul
362d0 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 43 2c 4e t_zeroblob64(C,N
362e0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 ).** interfaces
362f0 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f set the result o
36300 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
36310 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
36320 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 42 4c on to be.** a BL
36330 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c OB containing al
36340 6c 20 7a 65 72 6f 20 62 79 74 65 73 20 61 6e 64 l zero bytes and
36350 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 N bytes in size
36360 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
36370 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 ite3_result_doub
36380 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 le() interface s
36390 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 ets the result f
363a0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 rom.** an applic
363b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
363c0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 nction to be a f
363d0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 loating point va
363e0 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a lue specified.**
363f0 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 by its 2nd argu
36400 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ment..**.** ^The
36410 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36420 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 error() and sqli
36430 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
36440 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 16() functions.*
36450 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c * cause the impl
36460 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 emented SQL func
36470 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e tion to throw an
36480 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e exception..** ^
36490 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
364a0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 string pointed t
364b0 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 o by the.** 2nd
364c0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c parameter of sql
364d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
364e0 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 r() or sqlite3_r
364f0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a esult_error16().
36500 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f ** as the text o
36510 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 f an error messa
36520 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 ge. ^SQLite int
36530 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f erprets the erro
36540 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 r.** message str
36550 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ing from sqlite3
36560 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
36570 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 as UTF-8. ^SQLit
36580 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 e.** interprets
36590 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 the string from
365a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
365b0 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d rror16() as UTF-
365c0 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 16 in native.**
365d0 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 byte order. ^If
365e0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
365f0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
36600 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a result_error().*
36610 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 * or sqlite3_res
36620 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 ult_error16() is
36630 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 negative then S
36640 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 QLite takes as t
36650 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 he error.** mess
36660 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 age all text up
36670 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 through the firs
36680 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 t zero character
36690 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 ..** ^If the thi
366a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
366b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
366c0 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c rror() or.** sql
366d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
366e0 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 r16() is non-neg
366f0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 ative then SQLit
36700 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e e takes that man
36710 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 y.** bytes (not
36720 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d characters) from
36730 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
36740 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 er as the error
36750 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 message..** ^The
36760 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36770 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 error() and sqli
36780 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
36790 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 16().** routines
367a0 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 make a private
367b0 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f copy of the erro
367c0 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 r message text b
367d0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 efore.** they re
367e0 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 turn. Hence, th
367f0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 e calling functi
36800 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 on can deallocat
36810 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 e or.** modify t
36820 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 he text after th
36830 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 ey return withou
36840 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 t harm..** ^The
36850 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
36860 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 rror_code() func
36870 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 tion changes the
36880 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 error code.** r
36890 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 eturned by SQLit
368a0 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 e as a result of
368b0 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 an error in a f
368c0 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 unction. ^By de
368d0 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 fault,.** the er
368e0 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 ror code is SQLI
368f0 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 TE_ERROR. ^A su
36900 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f bsequent call to
36910 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36920 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 error().** or sq
36930 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
36940 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 or16() resets th
36950 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 e error code to
36960 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a SQLITE_ERROR..**
36970 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
36980 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f _result_error_to
36990 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 obig() interface
369a0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 causes SQLite t
369b0 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 o throw an.** er
369c0 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 ror indicating t
369d0 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 hat a string or
369e0 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 BLOB is too long
369f0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a to represent..*
36a00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
36a10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 3_result_error_n
36a20 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 omem() interface
36a30 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 causes SQLite t
36a40 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 o throw an.** er
36a50 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 ror indicating t
36a60 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c hat a memory all
36a70 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a ocation failed..
36a80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
36a90 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 e3_result_int()
36aa0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
36ab0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
36ac0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ** of the applic
36ad0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
36ae0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 nction to be the
36af0 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 32-bit signed i
36b00 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 nteger.** value
36b10 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 given in the 2nd
36b20 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 argument..** ^T
36b30 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
36b40 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 t_int64() interf
36b50 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 ace sets the ret
36b60 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 urn value.** of
36b70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
36b80 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
36b90 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 to be the 64-bi
36ba0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
36bb0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 .** value given
36bc0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d in the 2nd argum
36bd0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ent..**.** ^The
36be0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e sqlite3_result_n
36bf0 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 ull() interface
36c00 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 sets the return
36c10 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 value.** of the
36c20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
36c30 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
36c40 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e be NULL..**.** ^
36c50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
36c60 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 lt_text(), sqlit
36c70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
36c80 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 (),.** sqlite3_r
36c90 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 esult_text16le()
36ca0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 , and sqlite3_re
36cb0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 sult_text16be()
36cc0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 interfaces.** se
36cd0 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c t the return val
36ce0 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ue of the applic
36cf0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
36d00 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 nction to be.**
36d10 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 a text string wh
36d20 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 ich is represent
36d30 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 ed as UTF-8, UTF
36d40 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 -16 native byte
36d50 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 order,.** UTF-16
36d60 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 little endian,
36d70 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e or UTF-16 big en
36d80 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 dian, respective
36d90 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 ly..** ^The sqli
36da0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 te3_result_text6
36db0 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 4() interface se
36dc0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ts the return va
36dd0 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 lue of an.** app
36de0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
36df0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
36e00 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 69 6e a text string in
36e10 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 an encoding.**
36e20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
36e30 20 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73 74 fifth (and last
36e40 29 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 ) parameter, whi
36e50 63 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a ch must be one.*
36e60 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 * of [SQLITE_UTF
36e70 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 8], [SQLITE_UTF1
36e80 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 6], [SQLITE_UTF1
36e90 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 6BE], or [SQLITE
36ea0 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 _UTF16LE]..** ^S
36eb0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 QLite takes the
36ec0 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d text result from
36ed0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
36ee0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 from.** the 2nd
36ef0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 parameter of th
36f00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
36f10 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
36f20 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 s..** ^If the 3r
36f30 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
36f40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
36f50 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
36f60 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 es.** is negativ
36f70 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 e, then SQLite t
36f80 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 akes result text
36f90 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 from the 2nd pa
36fa0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 rameter.** throu
36fb0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 gh the first zer
36fc0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 o character..**
36fd0 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 ^If the 3rd para
36fe0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
36ff0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
37000 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 * interfaces.**
37010 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c is non-negative,
37020 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 then as many by
37030 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 tes (not charact
37040 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 ers) of the text
37050 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 .** pointed to b
37060 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 y the 2nd parame
37070 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 ter are taken as
37080 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
37090 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 -defined.** func
370a0 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 tion result. If
370b0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 the 3rd paramet
370c0 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 er is non-negati
370d0 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d ve, then it.** m
370e0 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 ust be the byte
370f0 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 offset into the
37100 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 string where the
37110 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 NUL terminator
37120 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 would.** appear
37130 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 if the string wh
37140 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 ere NUL terminat
37150 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 ed. If any NUL
37160 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 characters occur
37170 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e .** in the strin
37180 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 g at a byte offs
37190 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 et that is less
371a0 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f than the value o
371b0 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 f the 3rd.** par
371c0 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 ameter, then the
371d0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e resulting strin
371e0 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 g will contain e
371f0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 mbedded NULs and
37200 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f the.** result o
37210 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 f expressions op
37220 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e erating on strin
37230 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 gs with embedded
37240 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e NULs is undefin
37250 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 ed..** ^If the 4
37260 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
37270 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
37280 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
37290 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 ces.** or sqlite
372a0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 3_result_blob is
372b0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e a non-NULL poin
372c0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ter, then SQLite
372d0 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 calls that.** f
372e0 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 unction as the d
372f0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 estructor on the
37300 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 text or BLOB re
37310 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 sult when it has
37320 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 .** finished usi
37330 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a ng that result..
37340 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 ** ^If the 4th p
37350 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
37360 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
37370 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 ext* interfaces
37380 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 or to.** sqlite3
37390 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 _result_blob is
373a0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 the special cons
373b0 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 tant SQLITE_STAT
373c0 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a IC, then SQLite.
373d0 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 ** assumes that
373e0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 the text or BLOB
373f0 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f result is in co
37400 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 nstant space and
37410 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 does not.** cop
37420 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 y the content of
37430 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e the parameter n
37440 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 or call a destru
37450 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 ctor on the cont
37460 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 ent.** when it h
37470 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e as finished usin
37480 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a g that result..*
37490 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 * ^If the 4th pa
374a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
374b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
374c0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
374d0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 * or sqlite3_res
374e0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 ult_blob is the
374f0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 special constant
37500 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e SQLITE_TRANSIEN
37510 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 T.** then SQLite
37520 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
37530 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f the result into
37540 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 space obtained
37550 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 from.** from [sq
37560 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
37570 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e before it return
37580 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 s..**.** ^The sq
37590 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
375a0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ue() interface s
375b0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f ets the result o
375c0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 f.** the applica
375d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
375e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f ction to be a co
375f0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 75 6e py of the.** [un
37600 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
37610 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
37620 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
37630 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 2nd parameter.
37640 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
37650 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
37660 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 interface makes
37670 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 a copy of the [s
37680 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
37690 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 so that the [sq
376a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 lite3_value] spe
376b0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 cified in the pa
376c0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e rameter may chan
376d0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c ge or.** be deal
376e0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 located after sq
376f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
37700 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 ue() returns wit
37710 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 hout harm..** ^A
37720 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
37730 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
37740 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 t may always be
37750 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a used where an.**
37760 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
37770 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
37780 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c ect is required,
37790 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 so either.** ki
377a0 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 nd of [sqlite3_v
377b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e alue] object can
377c0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 be used with th
377d0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a is interface..**
377e0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 .** If these rou
377f0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
37800 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 from within the
37810 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
37820 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e d.** than the on
37830 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
37840 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
37850 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 ined function th
37860 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 at received.** t
37870 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 he [sqlite3_cont
37880 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 ext] pointer, th
37890 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
378a0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 defined..*/.void
378b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
378c0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e blob(sqlite3_con
378d0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
378e0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
378f0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
37900 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
37910 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e ob64(sqlite3_con
37920 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 text*,const void
37930 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 *,.
37940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 sq
37950 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69 lite3_uint64,voi
37960 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f d(*)(void*));.vo
37970 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
37980 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 t_double(sqlite3
37990 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c _context*, doubl
379a0 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 e);.void sqlite3
379b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 _result_error(sq
379c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
379d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 const char*, int
379e0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
379f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 result_error16(s
37a00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
37a10 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
37a20 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
37a30 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f _result_error_to
37a40 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e obig(sqlite3_con
37a50 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c text*);.void sql
37a60 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
37a70 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f r_nomem(sqlite3_
37a80 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 context*);.void
37a90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
37aa0 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 rror_code(sqlite
37ab0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3_context*, int)
37ac0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
37ad0 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 esult_int(sqlite
37ae0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3_context*, int)
37af0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
37b00 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 esult_int64(sqli
37b10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 te3_context*, sq
37b20 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f lite3_int64);.vo
37b30 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
37b40 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 t_null(sqlite3_c
37b50 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 ontext*);.void s
37b60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
37b70 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 xt(sqlite3_conte
37b80 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a xt*, const char*
37b90 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
37ba0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c oid*));.void sql
37bb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
37bc0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 64(sqlite3_conte
37bd0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a xt*, const char*
37be0 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c ,sqlite3_uint64,
37bf0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
37c00 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
37c10 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 (*)(void*), unsi
37c20 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 gned char encodi
37c30 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 ng);.void sqlite
37c40 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 3_result_text16(
37c50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
37c60 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
37c70 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 nt, void(*)(void
37c80 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 *));.void sqlite
37c90 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 3_result_text16l
37ca0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
37cb0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
37cc0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 int,void(*)(voi
37cd0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 d*));.void sqlit
37ce0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
37cf0 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 be(sqlite3_conte
37d00 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
37d10 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f , int,void(*)(vo
37d20 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 id*));.void sqli
37d30 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
37d40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
37d50 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 *, sqlite3_value
37d60 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 *);.void sqlite3
37d70 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 _result_zeroblob
37d80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
37d90 2a 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 *, int n);.int s
37da0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
37db0 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 roblob64(sqlite3
37dc0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 _context*, sqlit
37dd0 65 33 5f 75 69 6e 74 36 34 20 6e 29 3b 0a 0a 0a e3_uint64 n);...
37de0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
37df0 53 65 74 74 69 6e 67 20 54 68 65 20 53 75 62 74 Setting The Subt
37e00 79 70 65 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 ype Of An SQL Fu
37e10 6e 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 nction.** METHOD
37e20 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 : sqlite3_contex
37e30 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 t.**.** The sqli
37e40 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 te3_result_subty
37e50 70 65 28 43 2c 54 29 20 66 75 6e 63 74 69 6f 6e pe(C,T) function
37e60 20 63 61 75 73 65 73 20 74 68 65 20 73 75 62 74 causes the subt
37e70 79 70 65 20 6f 66 0a 2a 2a 20 74 68 65 20 72 65 ype of.** the re
37e80 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 sult from the ap
37e90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
37ea0 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 d function with
37eb0 63 6f 6e 74 65 78 74 20 43 0a 2a 2a 20 74 6f 20 context C.** to
37ec0 62 65 20 54 2e 20 20 4f 6e 6c 79 20 74 68 65 20 be T. Only the
37ed0 6c 6f 77 65 72 20 38 20 62 69 74 73 20 6f 66 20 lower 8 bits of
37ee0 74 68 65 20 73 75 62 74 79 70 65 20 54 20 61 72 the subtype T ar
37ef0 65 20 70 72 65 73 65 72 76 65 64 0a 2a 2a 20 69 e preserved.** i
37f00 6e 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f n current versio
37f10 6e 73 20 6f 66 20 53 51 4c 69 74 65 3b 20 68 69 ns of SQLite; hi
37f20 67 68 65 72 20 6f 72 64 65 72 20 62 69 74 73 20 gher order bits
37f30 61 72 65 20 64 69 73 63 61 72 64 65 64 2e 0a 2a are discarded..*
37f40 2a 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * The number of
37f50 73 75 62 74 79 70 65 20 62 79 74 65 73 20 70 72 subtype bytes pr
37f60 65 73 65 72 76 65 64 20 62 79 20 53 51 4c 69 74 eserved by SQLit
37f70 65 20 6d 69 67 68 74 20 69 6e 63 72 65 61 73 65 e might increase
37f80 0a 2a 2a 20 69 6e 20 66 75 74 75 72 65 20 72 65 .** in future re
37f90 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
37fa0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
37fb0 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65 3_result_subtype
37fc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
37fd0 2a 2c 75 6e 73 69 67 6e 65 64 20 69 6e 74 29 3b *,unsigned int);
37fe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
37ff0 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c : Define New Col
38000 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 lating Sequences
38010 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
38020 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 te3.**.** ^These
38030 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 functions add,
38040 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 remove, or modif
38050 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 y a [collation]
38060 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 associated.** wi
38070 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 th the [database
38080 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 connection] spe
38090 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 cified as the fi
380a0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a rst argument..**
380b0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 .** ^The name of
380c0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 the collation i
380d0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 s a UTF-8 string
380e0 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f .** for sqlite3_
380f0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
38100 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
38110 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
38120 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 v2().** and a UT
38130 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e F-16 string in n
38140 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
38150 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 for sqlite3_cre
38160 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
38170 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e )..** ^Collation
38180 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 names that comp
38190 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 are equal accord
381a0 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ing to [sqlite3_
381b0 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a strnicmp()] are.
381c0 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f ** considered to
381d0 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d be the same nam
381e0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 e..**.** ^(The t
381f0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 hird argument (e
38200 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 TextRep) must be
38210 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 one of the cons
38220 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a tants:.** <ul>.*
38230 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 * <li> [SQLITE_U
38240 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 TF8],.** <li> [S
38250 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a QLITE_UTF16LE],.
38260 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
38270 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 UTF16BE],.** <li
38280 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d > [SQLITE_UTF16]
38290 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 , or.** <li> [SQ
382a0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e LITE_UTF16_ALIGN
382b0 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a ED]..** </ul>)^.
382c0 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 ** ^The eTextRep
382d0 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d argument determ
382e0 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e ines the encodin
382f0 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 g of strings pas
38300 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f sed.** to the co
38310 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
38320 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c callback, xCall
38330 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 back..** ^The [S
38340 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 QLITE_UTF16] and
38350 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 [SQLITE_UTF16_A
38360 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 LIGNED] values f
38370 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 or eTextRep.** f
38380 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 orce strings to
38390 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 be UTF16 with na
383a0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
383b0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
383c0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 _UTF16_ALIGNED]
383d0 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 value for eTextR
383e0 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 ep forces string
383f0 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e s to begin.** on
38400 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 an even byte ad
38410 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 dress..**.** ^Th
38420 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
38430 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 t, pArg, is an a
38440 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 pplication data
38450 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 pointer that is
38460 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 passed.** throug
38470 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 h as the first a
38480 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 rgument to the c
38490 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
384a0 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a n callback..**.*
384b0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 * ^The fifth arg
384c0 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b ument, xCallback
384d0 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 , is a pointer t
384e0 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 o the collating
384f0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 function..** ^Mu
38500 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 ltiple collating
38510 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 functions can b
38520 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 e registered usi
38530 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 ng the same name
38540 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 but.** with dif
38550 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 ferent eTextRep
38560 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 parameters and S
38570 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 QLite will use w
38580 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 hichever.** func
38590 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 tion requires th
385a0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f e least amount o
385b0 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d f data transform
385c0 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 ation..** ^If th
385d0 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 e xCallback argu
385e0 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 ment is NULL the
385f0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 n the collating
38600 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 function is.** d
38610 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 eleted. ^When a
38620 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e ll collating fun
38630 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 ctions having th
38640 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 e same name are
38650 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 deleted,.** that
38660 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f collation is no
38670 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a longer usable..
38680 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 **.** ^The colla
38690 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ting function ca
386a0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
386b0 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 d with a copy of
386c0 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 the pArg .** ap
386d0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 plication data p
386e0 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 ointer and with
386f0 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 two strings in t
38700 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 he encoding spec
38710 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 ified.** by the
38720 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e eTextRep argumen
38730 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e t. The collatin
38740 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 g function must
38750 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 return an.** int
38760 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 eger that is neg
38770 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 ative, zero, or
38780 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 positive.** if t
38790 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 he first string
387a0 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 is less than, eq
387b0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 ual to, or great
387c0 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f er than the seco
387d0 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 nd,.** respectiv
387e0 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e ely. A collatin
387f0 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 g function must
38800 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 always return th
38810 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a e same answer.**
38820 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 given the same
38830 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 inputs. If two
38840 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e or more collatin
38850 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 g functions are
38860 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f registe